OS/2 Shareware BBS: 5 Edit/05-Edit.zip/p2help21.exe/HELP/CPE.HLP

OS/2 Help File | 1995-04-21 | 1MB | 38,595 lines

ΓòÉΓòÉΓòÉ 1. Beginner's Tutorial ΓòÉΓòÉΓòÉ

The "PREDITOR/2 Beginner's Tutorial" is designed to introduce you to the
product's features and highlight a few features for you to test.

To familiarize yourself with how PREDITOR/2 works with you to adapt to your
programming style and increase your productivity, read through the "Beginner's
Tutorial" and test the product for yourself.


ΓòÉΓòÉΓòÉ 1.1. Introduction to PREDITOR/2 ΓòÉΓòÉΓòÉ

Compuware Corporation introduces a new code editor for demanding OS/2
programmers who need an editor they can tailor to their specific requirements.
PREDITOR/2 is designed for OS/2 programmers who want to adjust their tools to
reach peak productivity.

PREDITOR/2, currently available by mail from Compuware and Indelible Blue, is a
graphical, 32-bit editor equipped with powerful features, including the ability
to display multiple windows, search across multiple files, edit and compile
simultaneously, and emulate other editors.  But for programmers who want more,
Compuware has taken the unusual step of providing access to most of
PREDITOR/2's own source code so you can customize existing features to your
liking and create new options.

With PREDITOR/2's Multiple Document Interface (MDI), you can view different
files in separate windows, or different sections of the same file in multiple
windows.  You can work in as many windows, buffers, and files as you want and
with as large a file as your system can handle. And you can undo and redo an
unlimited number of changes.

PREDITOR/2's dialog boxes enable you to quickly customize the editor's look and
feel. You can also point and click to set the editor to emulate the commands
and keystrokes of all previous generation editors--Brief, vi, Common User
Access (CUA), Emacs, and ISPF--and to automatically launch the compiler
appropriate for the programming language in use, whether it s C, C++, COBOL,
REXX, or a host of others.


ΓòÉΓòÉΓòÉ 1.1.1. Commonly used terms ΓòÉΓòÉΓòÉ

The following terms and definitions are used throughout the PREDITOR/2 online
help.

Buffer
          A buffer is your copy of the file that you are editing.  It is a
          temporary holding place from which you can view or edit a file.  The
          changes you make to a buffer do not affect its corresponding file
          until you save these changes.

          Unlike other editors, a buffer in PREDITOR/2 is not associated with a
          specific window. You can display any buffer in any window at any
          time. In multiple document interface (MDI) mode, you can display the
          same buffer in multiple windows.
Current
          Something that is active, or the focal point of activity. For
          example, the current position is the spot where the cursor is
          flashing. The current buffer is the buffer to which normal editing
          commands apply.
Dialog box
          A pop-up box (window) in which you enter information. These boxes are
          closed by pressing the appropriate button within the box or
          double-clicking on the icon in the upper left corner.
Display
          The area that is visible on the monitor (also use screen). Compare
          this to window, through which you view the contents of a buffer.
Keymap
          A keyboard definition that determines how your keyboard will behave.
          PREDITOR/2 uses a keymap to emulate other editors. You can also
          customize PREDITOR/2 by changing or adding your own keymaps.
Message box
          A pop-up window that contains a message or warning regarding the
          current action. You usually are not required to enter information in
          these boxes. Message boxes are closed by pressing the appropriate
          button within the box.
Scrap
          The scrap buffer is a temporary storage place and is not associated
          with any file or window. Any text that you wish to copy or move is
          placed into the scrap buffer. This is sometimes referred to as a
          clipboard.
Selection
          A marked block or region of text.
Window
          An area of the screen through which you can view the contents of a
          buffer. A window may take up the entire display or only a part of it,
          or may be as small as an icon. More than one window can be open while
          using PREDITOR/2 in MDI mode. You can change the size and location of
          a window, even overlapping them or positioning them side by side.
          Since a window is not associated with a specific buffer, you can use
          the buffer commands to change the buffer that is displayed in a
          window.


ΓòÉΓòÉΓòÉ 1.1.2. Installation Utility ΓòÉΓòÉΓòÉ

Unlike most OS/2 products, PREDITOR/2 provides an installation utility which
you use to update, restore, or delete the editor from your system.

To perform one of these activities,

 1. Double-click on the PREDITOR/2 folder icon.  The PREDITOR/2 - Icon View
    window appears, displaying several icons.

 2. Double-click on the Installation Utility icon.

    The Installation and Maintenance window opens, displaying a list of
    products you can work with.

 3. Select PREDITOR/2 2.1 from this list.

    Select the Action menu from the menu bar. This menu displays the different
    ways to modify the editor on your system.

 4. Change the editor's state as you desire, or simply close the Installation
    Utility by double-clicking in the box at the upper left corner of the
    window or selecting Exit from the File menu.

    The main editor window is displayed.

Note:  Personalizing the Editor

The Personalizing PREDITOR/2 section shows you how to alter PREDITOR/2 so that
your personalized preferences are automatically set each time you open the
editor.


ΓòÉΓòÉΓòÉ 1.1.3. The Stub Program ΓòÉΓòÉΓòÉ

A benefit of using PREDITOR/2 is your ability to quickly load the editor from
your OS/2 command line. The first time you run PREDITOR/2 (C.EXE), it starts an
editor session.  The stub program enables you to close this editor session and
re-open it later, at the exact location where you left off.  Most products
reload a copy of the product, while PREDITOR/2 opens the same copy.  The stub
program saves you time that other products require.

To return to PREDITOR/2 via the stub program,

 1. Open an OS/2 window.

 2. Type C or C.EXE at the command prompt and press Enter.

or

 1. Double-click on the PREDITOR/2 icon.

The editor window is displayed.


ΓòÉΓòÉΓòÉ 1.1.3.1. Advantages to Using the Stub ΓòÉΓòÉΓòÉ

Quick Loading Time

The first time you run C.EXE, it loads the full editor.  After that (assuming
you do not exit the editor), C.EXE loads quickly and passes its command line
parameters to the editor, which is already running.  Any files specified are
immediately opened.

Convenient Access

From an OS/2 window, you can easily start the editor using the stub program.
If you know the names of files that you want to edit, you can have these files
quickly loaded, open, and ready to edit.  For example, typing C:\CONFIG.SYS
*.CPP displays the editor with the CONFIG.SYS file and all .CPP files in the
current directory ready to edit.

Drag and Drop

As an alternative to typing a file name to start the editor with a specified
file, you can use the drag and drop method.  Simply drag and drop a file object
onto the stub icon (this icon was automatically created for you) or onto the
running editor. The editor is displayed in the foreground with the specified
file loaded, open, and ready to edit.

WorkFrame/2 Support

If you use the IBM WorkFrame/2, use the -W parameter when invoking C.EXE.  This
parameter enables you to load files in one running editor rather than loading a
new editor each time you double-click on a file name.  PREDITOR/2 also uses the
wf_goto_next_error() and wf_goto_prev_error() functions to step through the
list of WorkFrame/2 compile errors.


ΓòÉΓòÉΓòÉ 1.2. Personalizing PREDITOR/2 ΓòÉΓòÉΓòÉ

PREDITOR/2 is designed as a powerful editor which you can so fully adapt to
your personal preferences that the product becomes almost transparent.  It is
an editor that works the way you want it to work and doesn't get in your way.
By personalizing the editor, you can more easily do your job without a lot of
overhead.

There are three approaches toward personalizing your editor:

Customizing using the Settings notebook.

Configuring by editing the CPE.CFG file and LOCAL.PEL file.

Programming with the Professional Extension Language.


ΓòÉΓòÉΓòÉ 1.2.1. Customizing ΓòÉΓòÉΓòÉ

One of the ways in which PREDITOR/2 distinguishes itself from other text
editors is its extensive customization options.  Customizing your work
environment to suit your needs can increase your productivity.  However, if
customizing your editor is a time-consuming and tedious task, you are not
likely to do it. Fortunately, PREDITOR/2 enables you to make modifications
easily and become more productive more quickly.

In this Section

Notebook settings

The Options Menu


ΓòÉΓòÉΓòÉ 1.2.1.1. The Options Menu ΓòÉΓòÉΓòÉ

To customize, simply click on the Options menu in the menu bar and select the
feature you wish to modify. PREDITOR/2 has intuitive dialog boxes that quickly
guide you through making changes.


ΓòÉΓòÉΓòÉ 1.2.1.2. Notebook Settings ΓòÉΓòÉΓòÉ

The first step to personalizing your editor is to open the Settings notebook.
This notebook provides an easy, user-friendly method for customizing your
editor, window, and buffer behaviors.

To open the Settings notebook:

 1. Select the Options menu on the menu bar.

 2. Select the Settings option.

    The Settings dialog box is displayed.  By default, this notebook opens to
    the Editor Settings tab.


ΓòÉΓòÉΓòÉ 1.2.1.2.1. Notebook Tabs ΓòÉΓòÉΓòÉ

The Settings notebook is dived into three tabs:

Editor--settings which dictate how the editor behaves.  These settings affect
all buffers and windows.

Window--settings which dictate how a specific window behaves.

Buffer--settings which dictate how a specific buffer behaves.

These tabs appear along the right side of the notebook. Clicking on a tab will
"turn" the notebook page to that topic.


ΓòÉΓòÉΓòÉ 1.2.1.2.2. Subtopics ΓòÉΓòÉΓòÉ

Each topic has related subtopics which are named on the tabs appearing at the
bottom of the notebook. These subtopics are specific to a topic and change
accordingly. Not all editor subtopic tabs can appear along the bottom of the
notebook at one time.  By clicking on the arrows at the lower right corner of
the notebook page, you can turn the pages and thus see additional subtopic
tabs.

The lists below name each Settings notebook subtopic and the preferences you
can specify on the corresponding subtopic page

Editor Settings Subtopics

Emulation--Select emulation mode.

ISPF--Specify parameters for the ISPF emulation mode.

Save--Specify Save preferences.

Search--Specify Search preferences.

Status bar--Set the status bar's behavior.  (For example, select prompts for
the Brief, vi, and Emacs emulations.)

Message Level--Select the level of messaging you would like to see when working
in the editor.

Directories--Indicate the directories you would like to use for the editor's
files.

Extensions--Specify parameters for your compilers, such as:  extension,
compiler, template, matching pairs, tab stops, and margins.

VCS--Specify the commands the editor executes when you have the version control
system (VCS) enabled and want to use the get and put commands.

Window Settings Subtopics

Miscellaneous--Specify general information for the current window, such as
scroll bar behavior and line number formats.

Visible strings--Indicate how you want certain parts of the text in your window
to appear.

Scroll variables--Specify the number of lines or columns the cursor will move
when you scroll.

Buffer Settings Subtopics

Buffer flags--Specify common buffer settings, such as word processing
activities and read-only status.

Tabs/Margins--Specify tabs and margins for buffers.


ΓòÉΓòÉΓòÉ 1.2.1.3. Changing Notebook Settings ΓòÉΓòÉΓòÉ

Most notebook settings can be changed by selecting or clearing a check box,
selecting a radio button, or entering a value in a text box.  Selections are
implemented when you change notebook pages.


ΓòÉΓòÉΓòÉ 1.2.1.3.1. Setting Default Values ΓòÉΓòÉΓòÉ

The Make default check box is included on most Window notebook settings pages.
By checking the Make default box, you can apply the settings you select to all
new windows.

For example,

 1. Select the Window topic tab at the right side of the notebook.

 2. Click on the Scrolling subtopic tab at the bottom of the notebook.

 3. Enter your scroll context variable preferences using the spin buttons.

 4. Check the Make default box.

    The preferences you entered will now apply to all new windows.


ΓòÉΓòÉΓòÉ 1.2.1.3.2. Applying Settings to All Windows ΓòÉΓòÉΓòÉ

You will see Apply to all check boxes on all Window notebook settings pages.
By clicking on the check box (so that a checkmark appears in the box) you can
apply your selected settings to all currently open windows.


ΓòÉΓòÉΓòÉ 1.2.1.4. You Can Also Customize. . . ΓòÉΓòÉΓòÉ

Colors

Fonts

Key bindings

Keyboard macros


ΓòÉΓòÉΓòÉ 1.2.2. Configuring ΓòÉΓòÉΓòÉ

When you load PREDITOR/2, it goes through an initialization process that
includes executing the function local_setup(), and reading and executing the
statements in the CPE.CFG (configuration) file.  The function local_setup() is
located in the LOCAL.PEL file.


ΓòÉΓòÉΓòÉ 1.2.2.1. CPE.CFG ΓòÉΓòÉΓòÉ

This file stores user options that are likely to change often.  Because the
CPE.CFG file does not have to be recompiled to implement changes, you can
change options stored here and the editor will recognize these changes the next
time it is started. Notebook settings and the state of the editor are also
stored in the CPE.CFG file.

The CPE.CFG file is similar to your AUTOEXEC.BAT file or CONFIG.SYS file, in
that it initiates settings and performs tasks you want completed every time you
start PREDITOR/2.

Note:  Quick Loading--The initial loading of PREDITOR/2 may be slowed down if
you store too many options in the CPE.CFG file.  Therefore, use the LOCAL.PEL
file to indicate options that are not likely to change often.


ΓòÉΓòÉΓòÉ 1.2.2.2. LOCAL.PEL ΓòÉΓòÉΓòÉ

This file contains the local_setup() function, which reads and executes the
statements in the CPE.CFG file.  Here, you can specify options that will not
change often.

You can also specify keystrokes that correspond with activities you frequently
perform.  These key definitions are located in the local_keys() function.  Key
definitions are applied to all emulation modes.

To modify LOCAL.PEL,

 1. Select Open from the File menu.  The Open dialog box is displayed.

 2. Enter the directory and name of your LOCAL.PEL file in the Open Filename
    text box.  For example, if you installed PREDITOR/2 in the default
    directory, type C:\CPE\PEL\LOCAL.PEL in this text box.

 3. Click on the OK button.  The LOCAL.PEL file appears in your current window.

 4. Edit the file to include your preferred options.

The editor will recognize your changes after you re-compile LOCAL.PEL.

To recompile LOCAL.PEL,

 1. Exit the editor.

 2. Open an OS/2 window.

 3. Make current the PEL subdirectory of your editor directory (the default
    directory is C:\CPE\PEL).

 4. Execute the MAKE_AE.CMD file.

You have just recompiled LOCAL.PEL. PREDITOR/2 will now recognize your options
and key definitions every time you run the editor.


ΓòÉΓòÉΓòÉ 1.2.3. Programming ΓòÉΓòÉΓòÉ

For customers who want more, Compuware has taken the unusual step of providing
access to most of PREDITOR/2's own source code, so you can personalize existing
features to your liking and create new options.


ΓòÉΓòÉΓòÉ 1.2.3.1. Our C-Like Extension Language ΓòÉΓòÉΓòÉ

PREDITOR/2's configurability lies largely with its Professional Extension
Language (PEL). Therefore, you have the option to create a new function or
change an existing function to your specifications.  PEL encourages
customization and configuration through its industry acceptance and
ease-of-use.

PEL is the piece of PREDITOR/2 that truly makes this editor unique.  You can
use PEL to make your editor work according to the way you do.


ΓòÉΓòÉΓòÉ 1.2.3.2. PEL Debugger ΓòÉΓòÉΓòÉ

The PEL debugger is a tool to help you quickly and easily debug your PEL
functions.  This debugger operates much like a "C" debugger.

To use the PEL debugger,

 1. Select the Tools menu on the menu bar.

 2. Click on the PEL debugger menu item.  The PEL debugger is displayed.

 3. From the File menu, open the file you want to debug.

 4. Set breakpoints (by double-clicking at the beginning of a line) wherever
    necessary.

 5. Click on the Go button.

The PEL debugger window is hidden and the PREDITOR/2 window is displayed.  At
this point you can continue using the editor normally until the PEL code in
which you have set breakpoints executes.

Note:  Before Debugging

To debug PEL functions, you must first compile the .AE file without the
_compress option.  Make this change by editing the MAKE_AE.CMD file in your PEL
subdirectory.  Then rename the file to CPE.AE and recompile the function
library.

When a breakpoint is executed, the editor window is disabled and the debugger
window appears on your screen.

This window highlights the source code of the current breakpoint.  You can
query the value of any variable, step through PEL code, and determine the
source of errors.  For more information on using the PEL debugger, refer to
Chapter 4 in the PREDITOR/2 User's Guide, "Programming with PEL".


ΓòÉΓòÉΓòÉ 1.2.3.3. Command Dialog Box ΓòÉΓòÉΓòÉ

PREDITOR/2 provides a command dialog box from which you can issue PEL commands
or display the value of a variable.  This provides you easy access to all PEL
commands.

To use the command dialog box,

 1. Select the Tools menu from the menu bar.

 2. Click on the Command dialog menu item.  The Enter Command dialog box is
    displayed.

 3. Enter a PEL command or select a command from the command history list.

 4. Click on the OK button.


ΓòÉΓòÉΓòÉ 1.2.3.4. Compiler ΓòÉΓòÉΓòÉ

The benefit of the PEL compiler is that it is an incremental compiler, so that
when you recompile your CPE.AE function library, only the changed modules are
recompiled.  Thus, you spend a minimal amount of time waiting for the function
library to recompile after making minor changes.

The PEL compiler supplied with PREDITOR/2 is a special version of Thompson
Automation, Inc.'s AWK compiler.  The AWK compiler creates stand-alone
executables from AWK source code, while the PEL compiler produces programs that
PREDITOR/2 can execute.


ΓòÉΓòÉΓòÉ 1.2.3.5. The PEL Advantage ΓòÉΓòÉΓòÉ

Rather than changing the LOCAL.PEL file, you can use PEL to modify another file
or make your own file.

After compiling the editor, you can assign a key to your PEL functions.  You
can define keys for your new functions in the local_key() function, in the
CPE.CFG file, or in the Keybindings dialog box (found on the Options menu).


ΓòÉΓòÉΓòÉ 1.2.3.6. Additional PEL Features. . . ΓòÉΓòÉΓòÉ

Tags (see the PREDITOR/2 User's Guide)

PEL Function and Variable Reference manual

PEL Functions and Variables by Category manual


ΓòÉΓòÉΓòÉ 1.3. Search and Change ΓòÉΓòÉΓòÉ

The ability to search for and change information is extremely valuable.
Because PREDITOR/2 handles unusually large files, functional search and change
support streamlines the process of updating your code.

In this Section. . .

o Search

o Change

o Regular Expressions to Use When Searching

o Group and Match Group Searching

o Positioning the Cursor


ΓòÉΓòÉΓòÉ 1.3.1. Search ΓòÉΓòÉΓòÉ

The Search menu contains options that enable you to perform a variety of
searches, based on different types of search criteria. When you invoke a
search, the current default search settings are presented in the Find String
dialog box.  You can change any of these settings to search as you wish.

To initiate a search,

 1. Select the Search menu from the menu bar. The Search menu is displayed on
    your screen.  The items in this menu guide you toward performing a
    detailed, direct search according to your needs.  In this example, we will
    search for a string, using wildcards in the string's name.

 2. Select the Find string option from the Search menu.

 3. Type local_*\( in the Search value text box.

 4. In the Scope group box, select the File(s) radio button.

 5. Enter the files you would like to search in the Files to search text box.
    For this example, type C:\CPE\PEL\*.PEL (or substitute your installation
    directory.)

 6. Click on the Options button.  The Find String dialog box enlarges,
    presenting options that enable you to further define your search. Click on
    any of these options that pertain to how you would like to conduct your
    search. This Options button has been selected in the example above.

 7. Select the Find all button.

    The editor searches for all occurrences of the string local_*\( in the PEL
    file. You can follow the editor's search progress by watching found string
    locations appear in the Find All List dialog box.

    When the search is complete, the number of files found is displayed in the
    status bar at the lower left of the Find All List dialog box. You can halt
    the search process at any time by selecting the Stop button from the dialog
    box.

    Use the buttons on the Find All List dialog box to view the strings
    matching local_*\(.  As you move through the strings listed in the Find
    Files List dialog box, the cursor in the main editor window moves to the
    corresponding file and location.

Note: ERR buttons

The PREDITOR/2 toolbar displays two buttons which enable you to more quickly
flip through a list of matching search strings without using the Find All List
dialog box.  These are the ERR buttons, located near the right end of the
toolbar:

When you have completed a search and the results are presented in the Find All
List dialog box,

 1. Minimize the Find All List dialog box by clicking on the upper right corner
    of the dialog box.

 2. Click on  the ERR buttons to move forward and backward through the results
    list.  Your cursor will automatically move to the next occurrence found by
    the search process.

Note:  Quick Context-Sensitive Search

Use the pop-up menu for a quick, context-sensitive search.  Within the buffer
you are searching, simply move the cursor to the word you are searching for,
press and release the right mouse button, and select the Find String menu item
from the pop-up menu that appears.


ΓòÉΓòÉΓòÉ 1.3.1.1. Change ΓòÉΓòÉΓòÉ

The Change option in the Search menu enables you to replace a specific string
with a new string.  This option works only in your current file.

To replace a string,

 1. Select Change from the Search menu.

    or

    Click on the Change icon on the toolbar.

    A Change String dialog box is displayed.

 2. Type the string you want to replace in the String value text box.  For this
    example, type cpe.

 3. Type the new value for the string in the Change to value text box.  For
    this example, type PREDITOR/2.

 4. Select the Options button.  The Change String dialog box will enlarge to
    display options for further defining your search. (This button has been
    selected in the figure above.)

The buttons across the bottom of the Change String dialog box provide several
approaches toward changing strings.  Depending on how closely you want to
supervise the change process, you can click on any of these buttons to initiate
or cancel the process.  For specific information on when to use these buttons,
click on the Help button.


ΓòÉΓòÉΓòÉ 1.3.2. Regular Expressions ΓòÉΓòÉΓòÉ

PREDITOR/2 supports the following metacharacters used with regular expressions:

\                   Treats as normal character:  \$ finds $.

^                   Matches the beginning of the line.

$                   Matches the end of the line.

<                   Matches the beginning of the word.

>                   Matches the end of the word.

.                   Matches any character (except \n).

r*                  Matches zero or more of r.

.*                  Matches any string (except \n).

r+                  Matches one or more of r.

r?                  Matches zero or one of r.

|                   Alternation operator; i.e., is|are finds is or are.

(r)                 Treats r as a group.

[r]                 Treats r as a match group.

[abc]               Finds characters abc.

[^abc]              Finds any characters except abc.

[a-z]               Hyphen between characters (a-z) indicates range.


ΓòÉΓòÉΓòÉ 1.3.3. Group and Match Group Searching ΓòÉΓòÉΓòÉ

A group is one or more characters treated as a unit.  A match group is a type
of group that encloses part of a regular expression in braces ({}).  Groups are
typically used to show association or precedence.

The content of a match group has the same form as a group, except that
PREDITOR/2 assigns a reference number (1 through 9) to each match group.
Instead of typing the text, you can use the reference number.

For example,

 1. Type the following value in the Search value text box in the Change String
    dialog box:

    {Sailboat .*} (is|are) {fun.}

    This expression contains two match groups and one group. PREDITOR/2 assigns
    reference numbers 1 and 2 to the match groups.  It does not assign a number
    to the group defined by parentheses.

 2. In the Change to value text box, type :

    \1 can be \2

This replacement text tells PREDITOR/2 to reuse the first string, substitute
the words can be for is or are, and reuse the second string.  The table below
shows two sentences that were found, and how they were changed:

Found Text                  Changed to...

Sailboat races are fun.     Sailboat races can be fun.

Sailboat racing is fun.     Sailboat racing can be fun.


ΓòÉΓòÉΓòÉ 1.3.4. Positioning the Cursor ΓòÉΓòÉΓòÉ

When creating a regular expression, you can specify the location within a
string where, after a search operation, you want to begin editing.

For example, given the string Dear Dr\.[]+\c:, PREDITOR/2 searches for the text
Dear Dr. followed by one or more spaces and a single colon and positions the
cursor before the colon.  If the cursor location were not specified, PREDITOR/2
would place the cursor at the beginning of the matching text (in this example,
at the D of the word Dear).


ΓòÉΓòÉΓòÉ 1.3.5. Additional Search and Change Features ΓòÉΓòÉΓòÉ

o Find next occurrence of string

o Locate specific line number

o Find routines


ΓòÉΓòÉΓòÉ 1.4. Text Manipulation ΓòÉΓòÉΓòÉ

PREDITOR/2's text manipulation features enable you to work quickly with text,
using either the keyboard or the mouse.

In this Section. . .

o Unlimited undo and redo

o Add bookmarks

o Editing Text with the Mouse

   - Select column
   - Select line
   - Select block

o Word processing


ΓòÉΓòÉΓòÉ 1.4.1. Unlimited Undo and Redo ΓòÉΓòÉΓòÉ

When you edit text, there is no limit to how far you can undo and redo actions.
With PREDITOR/2, this is quickly and easily accomplished through the Undo and
Redo buttons on the toolbar.


ΓòÉΓòÉΓòÉ 1.4.2. Bookmarks ΓòÉΓòÉΓòÉ

Bookmarks represent marked locations within your file where you can position
your cursor. This feature is especially useful when you are working with large
files.  By assigning a name to each bookmark, you can quickly return to that
location by selecting the appropriate bookmark name using the Bookmark list
option from the Search menu.

Unlimited Availability

While some code editors limit the number of bookmarks you can place, PREDITOR/2
sets no limits.


ΓòÉΓòÉΓòÉ 1.4.3. Editing Text with the Mouse ΓòÉΓòÉΓòÉ

PREDITOR/2 supports both mouse and keyboard use for editing text.  You can use
the mouse to move the cursor position, make an inactive window active, mark
text, and create new windows.

Note: Supporting a 3-button mouse

If your mouse has three buttons rather than two, you can add commands for the
center button.  Refer to the "User Interface" chapter in the PREDITOR/2
Professional Extension Language Functions and Variables by Category manual.

The table below summarizes the mouse actions you can use when editing text in
PREDITOR/2.

Mouse Commands for Editing Text

Activity               Corresponding Mouse Action

Position cursor        Click in window.

Mark text block        Click and drag up or down.

Mark column block      Click and drag while pressing the Ctrl key or click with
                       the right mouse button and drag.

Mark a single line     Click and drag across the line while pressing the Alt
                       key.

Mark multiple lines    Click and drag up or down while pressing the Alt key.


ΓòÉΓòÉΓòÉ 1.4.3.1. Creating Windows ΓòÉΓòÉΓòÉ

If you are in MDI mode (see "File Manipulation") you can use the mouse to
create a window.

In the main PREDITOR/2 window,

 1. Position the mouse cursor where you want the lower left corner of the
    window to rest.

 2. Hold down the left mouse button and drag diagonally away from this corner.

 3. When you reach the location for the opposite window corner, release the
    mouse button.

    There is no limit to the number of windows you can create.


ΓòÉΓòÉΓòÉ 1.4.4. Word Processing ΓòÉΓòÉΓòÉ

The functions described below make word processing with PREDITOR/2 fast and
easy.

o Tabs and Margins

o File Extensions

o Word Processing Mode

o Word Wrap

o Paragraph Flow

o Toolbar


ΓòÉΓòÉΓòÉ 1.4.4.1. Tabs and Margins ΓòÉΓòÉΓòÉ

The left and right margins are only used when you are in word processing mode.
On the Misc. page of the Buffer settings notebook, set the left and right
margins at 4 and 70, respectively.  Also, set a tab stop to match your left
margin, i.e., 4 7.


ΓòÉΓòÉΓòÉ 1.4.4.2. File Extensions ΓòÉΓòÉΓòÉ

On the Extensions page of the Editor Settings notebook, specify an extension
for your text files.  A commonly used text file extension is .TXT.  From the
selections on the Extensions page, you can create a template for all of your
.TXT files. Indicate your word wrap preference by selecting or clearing the
Word Wrap check box.  You can specify tab stops and margin settings for your
template.  If you enter a tab stop or margin setting on this page, it overrides
the default values you entered on the Misc. page in the Buffers settings
notebook. Once you've created your template, whenever you edit a file with the
specified text extension, you are automatically in word processing mode.


ΓòÉΓòÉΓòÉ 1.4.4.3. Word Processing Mode ΓòÉΓòÉΓòÉ

You can switch to word processing mode for a buffer by entering the wp command
at an editor command prompt.  You can access a command prompt through the
Command dialog or System window functions from the Tools menu.


ΓòÉΓòÉΓòÉ 1.4.4.4. Word Wrap ΓòÉΓòÉΓòÉ

When you are in word processing mode and have turned word wrap on, text lines
automatically wrap to the left margin when you type past the right margin.
When you add text in the middle of a line, the current text is not overwritten,
but the paragraph is reflowed.  If you press Enter in the middle of a line, the
line is split at the cursor position and the text to the right of the cursor is
moved to the first column of the next line.


ΓòÉΓòÉΓòÉ 1.4.4.5. Paragraph Flow ΓòÉΓòÉΓòÉ

Paragraphs are delimited by empty lines. The wrap_paragraph command reflows a
paragraph at the margins.  This is useful when editing a text file that has
different margins than those you have specified.

Before you execute wrap_paragraph, you must manually move all of the text to
the left margin.  This is easily done in Brief emulation by selecting all of
the text and pressing the Tab key.


ΓòÉΓòÉΓòÉ 1.4.4.6. Editing from the Toolbar ΓòÉΓòÉΓòÉ

Not only is text editing easy with PREDITOR/2, but your most basic editing
commands are available right on the PREDITOR/2 toolbar.

 Cut

 Copy

 Paste

 Undo

 Redo


ΓòÉΓòÉΓòÉ 1.4.5. Additional Text Editing Features ΓòÉΓòÉΓòÉ

o Change text case

   - Uppercase
   - Lowercase
   - Reverse

o Block indenting/outdenting


ΓòÉΓòÉΓòÉ 1.5. File Manipulation ΓòÉΓòÉΓòÉ

One of PREDITOR/2's strengths is its ability to handle large files while you
work with and manipulate these files.  Because PREDITOR/2 knows no limits, you
can work with files of any size, in as many buffers and windows as you like.
You can also compare the differences between two versions of a file. PREDITOR/2
makes manipulating large files a manageable task.


ΓòÉΓòÉΓòÉ 1.5.1. Using Multiple Document Interface (MDI) Mode ΓòÉΓòÉΓòÉ

PREDITOR/2 enables you to display an unlimited number of windows at one time.
This function is known as Multiple Document Interface (MDI) mode. MDI mode
enables you to view multiple files at the same time, or view the same files in
multiple places.  When MDI mode is enabled, all currently opened windows can be
displayed.  If MDI mode is disabled, PREDITOR/2 displays only one window at a
time.

To enable MDI mode,

 1. Click on the Windows menu on the menu bar. If the MDI mode is already
    enabled, a ( symbol is shown next to the MDI mode option.  You can close
    the menu and continue.

 2. If the MDI mode option is disabled, click on the MDI mode option. A (
    symbol appears next to the MDI mode selection, indicating that MDI mode is
    enabled.


ΓòÉΓòÉΓòÉ 1.5.1.1. Disabling MDI Mode ΓòÉΓòÉΓòÉ

To disable this option, select it from the Windows menu. The checkmark is
removed, indicating that the option is disabled.


ΓòÉΓòÉΓòÉ 1.5.2. Buffers and Windows ΓòÉΓòÉΓòÉ

In PREDITOR/2, you open both buffers and windows to work with files.  Although
the two work together, buffers and windows have distinct uses.  The following
sections define buffers and windows.


ΓòÉΓòÉΓòÉ 1.5.2.1. Buffers ΓòÉΓòÉΓòÉ

A buffer is your copy of a file that you are editing.  A buffer is a temporary
holding place.  You can edit a buffer, but the changes you make are not
included in its corresponding file until you save the file.

Unlike other editors, a buffer in PREDITOR/2 is not associated with a specific
window.  You can display any buffer in any window at any time.  In MDI mode,
you can display the same buffer in multiple windows.

To create a new buffer,

 1. Click on the File menu on the menu bar.

 2. Click on the New menu item.

or

 1. Click on the New Buffer icon on the toolbar.

You can use the options in the Buffer menu to move between and open buffers.

To switch to an existing buffer,

 1. Click on the Buffer menu on the menu bar.

 2. Click on the menu option you prefer.

 3. Follow the prompts that apply to the menu option you selected.


ΓòÉΓòÉΓòÉ 1.5.2.2. Windows ΓòÉΓòÉΓòÉ

A window is an area of the screen through which you can view the contents of a
buffer.  A window may take up the entire display or only a part of it, or may
be as small as an icon.

You can open multiple windows while using PREDITOR/2 in MDI mode.  You can
change the size and location of a window, overlap windows or position them
side-by-side. See the Windows menu on the menu bar for windows options.  For
example, the windows below are tiled.

Since a window is not associated with a specific buffer, you can use the buffer
commands to change the buffer that is displayed in a window, or delete the
window without affecting the buffer.


ΓòÉΓòÉΓòÉ 1.5.3. Comparing Versions ΓòÉΓòÉΓòÉ

It is often handy to be able to compare two versions of a file and review the
differences between the versions.  PREDITOR/2 enables you to compare files with
the Vdiff tool.

To compare files,

 1. Click on the Tools menu on the menu bar.

 2. Click on the VCS menu item.  Another menu opens.

 3. Click on the Vdiff menu item.

    The PVCS VDIFF dialog box is displayed.

 4. Enter the name of the source file, and if necessary a revision/version
    number in the Reference text boxes.

 5. Enter the name of the target file and, if necessary, a revision/version
    number in the Target text boxes.

 6. Select either the Comparison or Vdiff output radio button (in the View
    group box) to specify how you want to view the compared results.
    Comparison will give you an outline view of the results, with changes
    highlighted.  Vdiff output will display the contents of the Vdiff buffer
    containing the two files, with plus (+) and minus (-) signs indicating
    additions and subtractions.

 7. If you choose to view the results in the Comparison mode, use the radio
    buttons in the Orientation group box to specify how the information will be
    displayed.

 8. Select or clear the Ignore whitespace check box.  If you select this check
    box, whitespace from indentation and other space differences is considered
    as part of the line.  This space can cause unnecessary error notations.
    Clear this box to ignore whitespace.

 9. Click on the OK button.  PREDITOR/2 will now present to you the version
    differences in your specified file and versions.


ΓòÉΓòÉΓòÉ 1.6. Programming Aids ΓòÉΓòÉΓòÉ

PREDITOR/2 is packed with extensive features to make programming easy and
flexible.

In this Section. . .

o Unlimited Compiler Support

o Language Templates

o Integrating with WorkFrame


ΓòÉΓòÉΓòÉ 1.6.1. Unlimited Compiler Support ΓòÉΓòÉΓòÉ

Not only does PREDITOR/2 provide many preset compilers, but it can support any
compiler you wish to use.

Add your own compiler in the Editor settings notebook, on the Extensions and
Compilers page.


ΓòÉΓòÉΓòÉ 1.6.2. Enabling Template Expansion ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 1.6.2.1. Specifying a Template ΓòÉΓòÉΓòÉ

The editor recognizes the extension of your file name and opens its
corresponding template.  For example, if you are editing a file named TEST.C, a
C template is expanded when you enable template expansion.


ΓòÉΓòÉΓòÉ 1.6.3. Integrating with WorkFrame/2 ΓòÉΓòÉΓòÉ

PREDITOR/2 integrates with IBM's WorkFrame/2.  This integration enables you to
specify the editor in which source files are displayed.  By specifying C.EXE -W
as the editor, PREDITOR/2 will be the editor used when accessing files or
locating errors from WorkFrame/2.

Benefits

The benefits of integrating with WorkFrame/2 are:

 1. Error Sources Displayed

    If your WorkFrame/2 compile generates error messages, you can double-click
    on an error message to display the corresponding source code in PREDITOR/2.
    You can then modify your source code to fix the error (or warning), and
    restart the compile process.  This saves you the trouble of manually
    loading the editor, choosing the correct file, and locating the appropriate
    line number.

 2. Single Editor Loaded

    Instead of loading a new copy of the editor into memory each time you need
    to view source code, the PREDITOR/2 stub (C.EXE) quickly brings the already
    running editor to the foreground, saving load time and memory.


ΓòÉΓòÉΓòÉ 1.7. Additional Programming Aids ΓòÉΓòÉΓòÉ

Language Templates

Integration

Preset Compilers

Tags Facility


ΓòÉΓòÉΓòÉ 1.7.1. Language Templates ΓòÉΓòÉΓòÉ

Automatic expansion:

C/C++
COBOL
REXX
PASCAL
AWK
Clipper 50
Clipper 87
dBase
FORCE


ΓòÉΓòÉΓòÉ 1.7.2. Integration ΓòÉΓòÉΓòÉ

OS/2 Workplace Shell drag and drop


ΓòÉΓòÉΓòÉ 1.7.3. Preset Compilers ΓòÉΓòÉΓòÉ

Preset compilers include:

IBM CSet/Cset++
Borland C/C++
Microsoft C/C++
Advantage ADA
Clipper 5.0
Clipper Summer '87
COBOL
FORCE
dBase
INTERSOLV PolyMake
INTERSOLV PVCS Builder
Lahey FORTRAN 77
Microsoft Masm
Microsoft Quick BASIC
NMake
PEL
Turbo C, C++ and Pascal
Zortech C/C++


ΓòÉΓòÉΓòÉ 1.7.4. Tags Facility ΓòÉΓòÉΓòÉ

Generate .tag files

Tags locate

CTags make

Peltags make

Find routines


ΓòÉΓòÉΓòÉ 1.8. Workgroup Support ΓòÉΓòÉΓòÉ

Version Control System

Before you can select any of the options available in the system, you must
enable the version control system (VCS).  To enable the VCS, select the Enable
VCS check box on the VCS page of the Editor settings notebook.

Get

Selecting Get enables you to retrieve a file from the version control system
and at the same time lock the file so that it cannot be released to another
user.  When you select Get, a dialog box displays the Get command.  This
command reflects the default value from the VCS page of the Editor settings
notebook.

Put

Selecting Put releases the lock on the file and returns it to the version
control system. When you select Put, a dialog box displays the Put command.
This command reflects the default value from the VCS page of the Editor
settings notebook.


ΓòÉΓòÉΓòÉ 1.9. Documentation ΓòÉΓòÉΓòÉ

PREDITOR/2 comes with complete printed and online documentation for both the
editor and the Professional Extension Language (PEL):

Product Manuals

PREDITOR/2 User's Guide

This document covers how to install PREDITOR/2 on your workstation, configuring
and customizing the editor, the user interface and basic functions, and using
the Professional Extension Language (PEL) to further customize PREDITOR/2.

PREDITOR/2 Quick Reference

For basic information on working with PEL and activities you perform daily,
refer to this manual.  Here you will find information outlining PEL, the
editor, emulation keymaps, template expansions, and ASCII codes.

 Professional Extension Language Functions and Variables by Category

 Here you will find the most commonly used PEL functions and variables arranged
by category.  Each category is described and followed by the related commands
and a summary of their purposes.  An alphabetical listing of functions and
variables also helps you to find the category pertaining to a specific function
or variable.

Professional Extension Language Function and Variable Reference

For detailed information on all PEL functions and variables, refer to this
manual.  Here you will find every PEL command and its related purpose, syntax,
type, description, value returned, and examples.

Online Help

PREDITOR/2's online help provides extensive information on:

o Functions and variables

o Menu items

o Settings notebook options

o General product information

o Technical support information.

The Help menu puts on-line and context-sensitive help at your fingertips.  In
all standard keymaps and most emulation packages, the online help facility is
available by pressing F1 on your keyboard. You can access Help from any menu by
pressing F1 and from some dialog boxes by selecting the Help push button.

You can also access any other product's online help through the NDX files.


ΓòÉΓòÉΓòÉ 1.10. Additional Features ΓòÉΓòÉΓòÉ

The many different ways you can work with PREDITOR/2 make it a comfortable
product to work with on a daily basis.  Beyond the powerful features you've
seen so far, here are a few more that make this editor satisfying to our
customers.

In this Section. . .

Status bar prompts

GUI prompts

File and Command Name Completion

History Lists

Additional Features


ΓòÉΓòÉΓòÉ 1.10.1. Status Bar Prompts ΓòÉΓòÉΓòÉ

The status bar displays information regarding your current PREDITOR/2 session.
The status bar is located at the lower left of the main PREDITOR/2 window.

You can customize the status bar to provide command line prompts and other
information on the Status Bar page of the Editor settings notebook.  If you
select the Prompts option on this page, you can enter commands from the status
bar, in all emulations other than CUA.

To activate a command prompt from the status bar in the Brief emulation,

 1. Type the keystroke command [Alt][E] from your keyboard.  A command prompt
    appears on your status bar.


ΓòÉΓòÉΓòÉ 1.10.2. GUI Prompts ΓòÉΓòÉΓòÉ

For a more GUI-like look, deselect the Prompts check box in the Editor settings
notebook.


ΓòÉΓòÉΓòÉ 1.10.3. File and Command Name Completion ΓòÉΓòÉΓòÉ

Suppose you can't remember the full name of a file or command.  Or suppose the
name is longer than you wish to type.  PREDITOR/2 completes file and command
names to help you work more quickly.

To have PREDITOR/2 complete a file or command name,

 1. Type the beginning of the name at the status bar prompt.

 2. Press the Tab key on your keyboard.  The correct name appears at the
    prompt.  If there is more than one name matching your request, a list of
    possible matches is displayed in a dialog box on your screen.  Double-click
    on the appropriate match or press the Enter key if there is only one match.


ΓòÉΓòÉΓòÉ 1.10.4. History Lists ΓòÉΓòÉΓòÉ

You can also view a history list by pressing the up arrow or Page Up key on
your keyboard.


ΓòÉΓòÉΓòÉ 1.10.5. Additional Features ΓòÉΓòÉΓòÉ

o Error tracking after compilation

o Background execution of language compilers


ΓòÉΓòÉΓòÉ 2. Installation Utility ΓòÉΓòÉΓòÉ

Unlike most OS/2 products, PREDITOR/2 provides an installation utility which
you use to update, restore, or delete the editor from your system.

To update, restore, or delete the editor from your system,

 1. Double-click on the PREDITOR/2 folder icon.  The PREDITOR/2 - Icon View
    window opens, displaying several icons.

 2. Double-click on the Installation Utility icon. The Installation and
    Maintenance window opens, displaying a list of products you can work with.

 3. Select PREDITOR/2 from this list.

 4. Select the Action menu from the menu bar. This menu displays the different
    ways to modify the editor on your system.

 5. Change the editor's state as you desire, or simply close the Installation
    Utility by double- clicking in the box at the upper left corner of the
    window or selecting Exit from the File menu.


ΓòÉΓòÉΓòÉ 3. Updating Your CONFIG.SYS File ΓòÉΓòÉΓòÉ

The installation program can automatically update your CONFIG.SYS file to
support PREDITOR/2  If you choose this option, the installation program adds
the PREDITOR/2 directories to the environment variables PATH, LIBPATH, and
HELP. It also adds a variable (CPE) that points to the executable directory.

If you choose not to have this done automatically, you'll need to manually make
the necessary changes to your CONFIG.SYS file.  These changes are outlined
below.

SET CPE=<drive:\dir>_

Modify the SET CPE variable to point to the PREDITOR/2 home directory
(<drive:\dir>).

LIBPATH_

Update the LIBPATH variable to include the DLL directory.  Do this by adding
<drive:\dir>\DLL to the variable, where <drive:\dir> indicates where PREDITOR/2
is installed.

PATH_

Update the PATH variable so that PREDITOR/2 can be run from any drive.  Do this
by adding <drive:\dir>\ to the variable, where <drive:\dir> indicates where
PREDITOR/2 is installed.

HELP_

Update the HELP variable so that PREDITOR/2 help is available from the editor.
Do this by adding <drive:\dir>\HELP to the variable, where <drive:\dir>
indicates where PREDITOR/2 is installed.

Updating the HELPNDX and DPATH environment variables is optional.  These
changes are outlined below.

HELPNDX_

View PREDITOR/2 help from other applications by adding NDX files to your
HELPNDX variable.  Add the fully unqualified name of the NDX file separated by
a + symbol to the environment variable.  For example:
HELPNDX=DICK.NDX+JEFF.NDX.

DPATH_

The paths of the NDX files specified in the HELPNDX variable must be specified
in the DPATH.  In the example above, if the fully qualified name of JEFF.NDX is
C:\SPOT\RUN\JEFF.NDX, C:\SPOT\RUN must be added to your DPATH environment
variable.


ΓòÉΓòÉΓòÉ 4. Quick Loading ΓòÉΓòÉΓòÉ

After your editor is installed, there are two tools that enable you to load the
editor quickly, with your preferences recognized upon startup.  To load
quickly, use the stub program or command line options.  For more information,
click on the highlighted sections below:

Using the Stub Program

Command Line Options


ΓòÉΓòÉΓòÉ 4.1. Using the Stub Program ΓòÉΓòÉΓòÉ

One of the benefits of using PREDITOR/2 is the ability to quickly load the
editor from your OS/2 command line. The first time you run PREDITOR/2 (C.EXE),
it starts an editor session.  If the editor is already running, the stub will
load files into the running editor instead of starting a new editor session.
Most products reload a copy of the product, while PREDITOR/2 opens the same
copy.  The stub program saves you time that other products require.

To return to the editor via the stub program,

 1. Open an OS/2 window.

 2. Type C or C.EXE at the command prompt and press [Enter].

or

 1. Double-click on the PREDITOR/2 icon.

The editor window is displayed.


ΓòÉΓòÉΓòÉ 4.1.1. Advantages to Using the Stub Program ΓòÉΓòÉΓòÉ

Quick Loading Time

The first time you run C.EXE, it loads the full editor. After that time
(assuming you do not close the editor), C.EXE loads quickly and passes its
command line parameters to the editor, which is already running.  Any files
specified are immediately opened.

Convenient Access

From an OS/2 window, you can easily start the editor using the stub program.
If you know the names of files that you want to edit, you can have these files
loaded, open, and ready to edit.  For example, typing C C:\CONFIG.SYS *.CPP
displays the editor with the CONFIG.SYS file and all .CPP files in the current
directory ready to edit.

Drag and Drop

As an alternative to typing the file name to start the editor with the
specified file, you can use the drag and drop method.  Simply drag and drop a
file object onto the PREDITOR/2 icon or onto the running editor.  The editor is
displayed in the foreground with the specified file loaded, open, and ready to
edit.

WorkFrame/2 Support

If you use IBM WorkFrame/2, use the -W Command Line Options  when invoking
C.EXE.  This parameter initializes the editor to accept errors from
WorkFrame/2.  By using C.EXE, files accessed in WorkFrame/2 will be loaded into
a single editor.  PREDITOR/2 also uses the wf_goto_next_error() and
wf_goto_prev_error() functions to step through the list of WorkFrame/2 compile
errors.

PREDITOR/2 supports WorkFrame/2 with OS/2 2.1 or higher.


ΓòÉΓòÉΓòÉ 4.2. Command Line Options ΓòÉΓòÉΓòÉ

When you load the editor from the OS/2 command line, you can indicate specific
options for the editor to recognize and perform when opened.  These command
line options enable you to work more quickly and customize the editor's state
upon loading the editor.

To use command line options when loading, simply add the option(s) and related
information after you type C, which loads the editor.

Note: The command line options A and C cannot be used with the stub programs.
All other command line options are valid with the stub program.

Option    Purpose

a, A      Use a specific function library.

c, C      Use a specific configuration file.

d, D      Enable DDE communications.  Allows communication with stub (default
          is on).

f, F      Run this PEL function.

g, G      Go to this line number in the file specified or the current buffer.

m, M      Start editor minimized.

n, N      Do not display startup progress indicator.

p, P      Playback keys

r         Open editor in read-only mode

R         Start recording keystrokes on startup.

t, T      Start editor in test mode

w, W      Start editor for WorkFrame Integration.

z, Z      Use [Ctrl][Z] as end of file.

Note: When using command line options, precede them with a dash (-) or forward
slash (/).


ΓòÉΓòÉΓòÉ 5. Customizing ΓòÉΓòÉΓòÉ

One of the ways in which PREDITOR/2 distinguishes itself from other text
editors is its extensive customization options.  Customizing your work
environment to suit your needs can increase your productivity.  However, if
customizing your editor is a time-consuming and tedious task, you are not
likely to do it.  Fortunately, PREDITOR/2 enables you to make modifications
easily and become more productive more quickly.

Refer to the following sections for specific information on how to customize
your editor:

Using the Notebook


ΓòÉΓòÉΓòÉ 5.1. Window Display ΓòÉΓòÉΓòÉ

PREDITOR/2 enables you to customize your window display to your liking. Refer
to the following sections for detailed information on customizing your window
display:

Window Display Modes

How to Customize Your Windows

Displaying Buffers


ΓòÉΓòÉΓòÉ 5.1.1. Window Display Modes ΓòÉΓòÉΓòÉ

There are three window "modes" from which you can choose:

Single
          Only one window is open for your editor session, and is attached to
          the main editor window.  Although you may have many open buffers, you
          can view just one at a time.

Multiple
          An unlimited number of windows may be open at one time, and are
          confined within the main editor window.

Detached
          Windows and toolbar are no longer limited to the main editor window.
          In Detached mode, the toolbar and windows "float"--enabling you to
          move them anywhere on the display.  The Control Panel dialog box is
          also displayed, containing the buffer list and access information for
          open buffers.  Closing the Control Panel box closes the editor.


ΓòÉΓòÉΓòÉ 5.1.2. How to Customize Your Windows ΓòÉΓòÉΓòÉ

Customize your window display using the Quick Settings or Settings items on the
Options menu.  Changing one item updates the information on the other.

To change your window display mode through the Quick Settings dialog box,

Select Quick Settings from the Options menu and click on the window mode you
prefer.  Then click on the Close button.  Your changes will be immediately
recognized.

To change your window display mode through the Settings notebook,

Select the Settings item on the Options menu.  The settings notebook will open.
Click on the Windows tab and then the Mode subtopic tab.  Select the window
mode you prefer, and click on the Close button.  Your changes will be
recognized immediately.  Note: If you are only changing your window display, we
recommend that you make changes using the Quick Settings dialog box.  This is
faster and easier than using the Settings notebook for a minor change.


ΓòÉΓòÉΓòÉ 5.1.3. Displaying Buffers ΓòÉΓòÉΓòÉ

In Multiple Document Interface (Multiple or MDI) mode or Detached mode, you
have the option to view one buffer per window.  If you select the One buffer
per window check box beneath your mode preference, each buffer will be opened
in a new window.


ΓòÉΓòÉΓòÉ 5.2. Using the Notebook ΓòÉΓòÉΓòÉ

The first step to personalizing your editor is to open the Settings notebook.
This notebook provides an easy, user-friendly method for customizing your
editor, window, and buffer behaviors.

To open the Settings notebook:

 1. Select the Options menu on the menu bar.

 2. Select the Settings option. The Settings dialog box is displayed.  The
    first page is the Editor Settings tab.

Notebook Topics

Notebook Subtopics

Changing Notebook Settings

Editor Settings

Window Settings

Types

Buffer Settings

File Settings


ΓòÉΓòÉΓòÉ 5.3. Notebook Topics ΓòÉΓòÉΓòÉ

The Settings notebook is divided into five topics:

Editor-settings which dictate how the editor behaves. These settings affect all
buffers and windows.

Window-settings which dictate how a specific window behaves.

Types-the types of buffers you will work with and how the editor will present
them (e.g. syntax highlighting, templates).

Buffer-settings which dictate how a specific type or buffer behaves.

File-settings which dictate how files are loaded into the editor (e.g. locked,
copied to memory).

These topics appear on tabs along the right side of the notebook. Clicking on a
tab will "turn" the notebook page to that topic.  You can also move between
pages by using the arrows at the lower-right corner of the notebook.


ΓòÉΓòÉΓòÉ 5.4. Notebook Subtopics ΓòÉΓòÉΓòÉ

Each topic has related subtopics which are named on the tabs appearing at the
bottom of the notebook. These subtopics are specific to a topic and change
accordingly. Not all editor subtopic tabs can appear along the bottom of the
notebook at one time.  By clicking on the arrows at the lower right corner of
the notebook page, you can turn the pages and thus see additional subtopic
tabs.


ΓòÉΓòÉΓòÉ 5.5. Changing Notebook Settings ΓòÉΓòÉΓòÉ

Most notebook settings can be changed by selecting or clearing a check box,
selecting a radio button, or entering a value in a text box.  Selections are
implemented when you change notebook pages.


ΓòÉΓòÉΓòÉ 5.5.1. Editor Settings ΓòÉΓòÉΓòÉ

Editor settings dictate how the editor will behave. These settings affect all
buffers and windows.  To make changes to buffer-specific or window-specific
settings, refer to Buffer Settings or Window Settings

Emulation

ISPF

Save

Search

Status Bar

Message Level

Directories

Cursor

VCS (Version Control System)


ΓòÉΓòÉΓòÉ 5.5.1.1. Emulation ΓòÉΓòÉΓòÉ

The options for customizing your emulation environment are described below.

Emulation mode
          From the list box, select the system you want the editor to emulate.
          The emulation mode you choose affects the way your keyboard behaves.
          For a complete list of emulation modes and keymaps, refer to Appendix
          A: Keymaps in the PREDITOR/2 User's Guide

If you are using an ISPF emulator, select ISPF from the list box and then click
on the ISPF Settings button to add additional customization and functionality.

See also:

o ISPF


ΓòÉΓòÉΓòÉ 5.5.1.1.1. ISPF Settings ΓòÉΓòÉΓòÉ

Customize the feel of the ISPF emulation using the options described below.

Default scroll amount
          The default scroll amount affects how much of the window will scroll.
          Valid values are:  Page=Scrolls a full page; HALF=Scrolls one-half
          page; CSR=Scrolls to the cursor position; N=Scrolls n number of lines
          or columns;  MAX= Scrolls to the extreme left, right, top, or bottom.

Enter key is 3270 [Return]
          Selected: The Enter key acts like a 3270 Return key. Thus, when you
          press [Enter], the cursor moves to the next line and no line commands
          are executed.  In addition when the "3270 [Return] to emulate a PC
          Enter" setting is selected, the Enter key moves the cursor and all
          data following the cursor to the next line.  Note:[Ctrl][Enter]
          functions the same as if [Ctrl] is pressed alone.
          Cleared:[Ctrl][Enter] emulates the 3270 Return key.  Thus, when you
          press [Ctrl][Enter], the cursor moves to the next line and no line
          commands are executed. In addition when the "[Ctrl][Return] to
          emulate a PC Enter" setting is selected, pressing and releasing
          [Ctrl] and [Enter] simultaneously moves the cursor and all data
          following the cursor to the next line. NOTE: [Enter] functions the
          same as if [Ctrl] is pressed alone.

Home key displays command line
          Selected: Press [Home] to display a command dialog box. Use the
          [Num-5] key to move the cursor to the top left position in the
          window. Cleared: Press [Home] to move the cursor to the top left
          position in the window.  Press the [Num-5] key to display a command
          dialog box.

[Home] and [End] move to edge of window ONLY
          Selected: Press [Home] or [End] to move the cursor only to the left
          and right edges of the visible window. Cleared: Pressing [Home] or
          [End] causes the cursor to move through the file, stopping at the
          edge of the line (to the beginning of the line numbers for [Home]),
          to the top or bottom of the window, and then to the top or bottom of
          the file.

Tab key emulates 3270 Tab
          Selected: Press [Tab] to move the cursor down one line at a time,
          moving between the line numbers and the data area of the window.
          Cleared: Press [Tab] to move the cursor between tab stops in the data
          area.

Cursor Left moves into Line Commands
          Selected: The cursor is permitted to move left, into the line command
          area. Cleared: When moving left, the cursor stops at the left edge of
          the data area and the screen begins to scroll.

END saves without asking (AUTOSAVE)
          Selected: The END command, F3 or PF3 saves and closes the current
          file. Cleared: The END command, F3 or PF3, closes the current file
          without saving it first.


ΓòÉΓòÉΓòÉ 5.5.1.2. Save ΓòÉΓòÉΓòÉ

By choosing the Save options tab, you can modify the Save settings and control
activities that occur when you exit the editor.  The table below describes each
Save setting.

Auto save
          PREDITOR/2 will periodically create a temporary copy of your modified
          buffers.  These copies will be deleted when a modified buffer is
          closed or the editor is exited normally. You can set the time between
          auto saves in the Auto save time (min.) check box, described below.

Save state on exit
          Upon exiting PREDITOR/2, the current state of all open buffers and
          windows is saved. The buffers and their contents, and the size and
          location of windows is recreated the next time you start PREDITOR/2.

Save settings on exit
          Saves the global editor settings that were in place when you exited
          the editor, and reestablishes them in your next editor session.
          These settings include:  notebook settings, colors, and fonts.

Create backup file
          Each time you save a modified file, the editor places a copy of the
          file as it existed before modifications in the backup directory you
          specified on the Directories notebook page.  The backup file has the
          same name and extension unless the backup directory is the same as
          that of the original file.  In this the case, the backup file is
          assigned and extension of .BAK.

Auto save time (min.)
          Indicates how often, in minutes, you want the editor to save a backup
          copy of your current buffer. The default time is one minute.  Note:
          The "Auto save" setting must be selected for this information to be
          recognized.

Save current directory on exit
          Saves your current directory when you exit, so your next editor
          session begins in that directory.

Save command history on exit
          Saves the last ten editor commands you executed before exiting the
          editor.  In your next editor session, you can recall these commands
          by pressing the up arrow while in a command dialog box.

Save search history on exit
          Saves a list of the last ten values you searched for during this edit
          session.  During your next editor session, you can recall these
          search values by pressing the up arrow at a search prompt.


ΓòÉΓòÉΓòÉ 5.5.1.3. Search ΓòÉΓòÉΓòÉ

When you start a search, a dialog box is displayed with the default search
settings.  These settings can be changed by clicking on Search in the notebook.
The table below describes each Search setting.

Search forward
          Search begins at the insertion point and moves forward to the end of
          the buffer.

Regular expressions on
          The search pattern is treated as a regular expression.

Highlight search results
          The located search string is shown as highlighted text.

Center search results
          The line containing the located search string is centered in the
          window.

Match whole word
          The search pattern must be delimited by one of the listed word
          delimiters to be considered a match.

Find maximal match
          The search attempts to find the largest group of characters that
          match the regular expression.  The Regular Expressions check box must
          be selected for this option to work.

Search wraps around
          If a search is invoked below the top of the buffer and the specified
          search string is not found before the search reaches the bottom of
          the buffer (or the top of the buffer in a backward search), the
          search wraps around the end of the buffer and continues searching
          until it returns to the starting point.

Match case
          To be considered a match, the case of the located text must match the
          search pattern.

Word delimiters
          Characters entered in this field define what delimits a word.  All
          functions that search for word boundaries use this setting.  White
          space is always included in the word delimiter and does not need to
          be specified here.


ΓòÉΓòÉΓòÉ 5.5.1.4. Status Bar ΓòÉΓòÉΓòÉ

The status bar enables you to easily locate information related to the current
buffer or window. By selecting the appropriate check box on the Status Bar
notebook page, you can specify the information that is displayed on the status
bar.

The table below describes the information presented on the status bar when you
select the corresponding setting on the Status bar page.

Prompts
          Prompts are displayed in the status bar.

Messages
          Messages are displayed in the status bar.

Column position
          The current column position of the cursor is displayed in the status
          bar.

Line number
          The current line number of the cursor is displayed in the status bar.

Total lines
          The total number of lines in the file is displayed in the status bar.

Emulation mode
          The current emulation mode is displayed in the status bar.

Other indicators
          Miscellaneous indicators are displayed. These include:  RO
          (read-only), MOD (modified), INS (insert mode), OVR (overwrite mode),
          NUM (numlock) and CAP(caps lock).

Day of week
          The current week day is displayed in the status bar.

Date
           The current date is displayed in the status bar.

Time
          The current time is displayed (in the format you specify) in the
          status bar.

Format
          Select the 12 hr. button for the time on your editor to be displayed
          in a 12-hour format, or the 24 hr. button to see the time in a
          24-hour format.

Dynamic resizing
          Each field of the status bar will be resized in order to display its
          information.  Any excess space is allocated to the message area.


ΓòÉΓòÉΓòÉ 5.5.1.5. Message Level ΓòÉΓòÉΓòÉ

Use Message Level options settings to specify the level of messages to be
displayed.  Messages are displayed on the status bar or in a dialog box,
depending on the status bar options you choose.

The table below describes the message level presented when you select the
corresponding setting on the Message level page.

All
          All messages are displayed.

Notify, warning and error
          Only notify, warning and error messages are displayed.

Warning and error
          Only warning and error messages are displayed.  (See "Pause on error"
          below.)

None
          No messages are displayed.

Pause on error
          Warnings and errors are displayed in pop-up message boxes, which must
          be closed before proceeding.  Clear this box to have warnings and
          errors displayed the same as messages.


ΓòÉΓòÉΓòÉ 5.5.1.6. Directories ΓòÉΓòÉΓòÉ

Use Directories settings to specify the directories in which files are stored
by the editor.

The table below describes the information to enter for the corresponding
setting on the Directories page.

Backup directory
          Location of backup files created by the editor.

Tags path
          Locations of .TAG files created when you select the Tags Make option
          from the Tools menu.  When you specify a tags path, each file must
          have an explicit path with each path delimited by semicolons. If this
          path is not set, the current directory is used. For example:

          C:CPE\PEL\PELTAGS.TAG;

          C:\PROJECT\CTAGS.TAG


ΓòÉΓòÉΓòÉ 5.5.1.7. Cursor ΓòÉΓòÉΓòÉ

Use the Cursor settings to tailor your cursor to your own preferences. The
following table describes each cursor setting.

Cursor type
          Click on one of the four cursor types available:

          1.Normal - Cursor displayed when in insert mode and in an area of the
          buffer where text has been typed.

          2.Overtype - Cursor displayed when in overtype mode and in an area of
          the buffer where text has been typed.

          3.Virtual - Cursor displayed when in insert mode and in an area of
          the buffer where text has not been typed.

          4.Virtual Overtype - Cursor displayed when in overtype mode and an
          area of the buffer where text has not been typed.

Cursor style
          Select Horizontal for a horizontal cursor, Vertical for a vertical
          cursor, or Custom to define your own cursor.  If you select Custom,
          the Width and Height fields are enabled for you to alter.

Width
          The cursor width, in pixels.

Height
          The cursor height, in pixels.

Gray
          The cursor color is gray.


ΓòÉΓòÉΓòÉ 5.5.1.8. VCS ΓòÉΓòÉΓòÉ

Use VCS (Version Control System) settings to tailor the version control system
to your preferences.

The table below describes the information to enter for the corresponding
setting on the VCS page.

Get command
          The VCS command used to "get" a file from your version control
          system.

Put command
          The VCS command used to "put" a file into your version control
          system.

Enable VCS
          Enables automatic "get" and "put" of read-only files.

Get on modification
          Prompts to "get" a read-only file when you begin to edit it.

Get when non-existent
          Prompts to get files that don't exist when you try to edit them.

Use the following macros to abbreviate information in your Get and Put text
fields:

This macro...  Means...

$<             Full specification

$r             Filename only

$e             Extension (no period)

$a             .AE file

$p             Path only

See also::

o Changing Settings
o pvcs()
o get_command
o PVCS Get Dialog
o put_command
o PVCS Put Dialog
o vdiff_command
o PVCS VDIFF Dialog


ΓòÉΓòÉΓòÉ 5.5.2. Window Settings ΓòÉΓòÉΓòÉ

Use the Window settings notebook pages to change the features of the current
window. You can check the Make default check box to establish default values
for all new windows.

There are two buttons at the bottom of each Windows settings page: Undo and
Default.  If you make changes on the page and want to return to the original
settings, click on Undo.  The settings specified prior to your changes (in the
current notebook) are displayed.  To change the settings to the editor's
default settings, click on Default.  The default settings are displayed.

Setting Default Values

The make default check box is included on all Window settings notebook pages,
except the Mode page.  By clicking on the Make default check box, the settings
you select are used for all new windows.

Applying Settings to All Windows

You will see apply to all check boxes on all Window settings notebook pages,
except the Mode page.  By clicking on the check box, you can apply your
selected settings to all currently open windows.

To tailor global editor settings, see Editor Settings  To customize buffer
settings, see Buffer Settings

Modes

Misc.

Visible strings

Scrolling


ΓòÉΓòÉΓòÉ 5.5.2.1. Mode ΓòÉΓòÉΓòÉ

PREDITOR/2 enables you to customize your window display to your liking.  The
Mode page lists the three modes you can choose from.  The following list
describes these modes and the One buffer per window option.

SDI (mode)
          Only one text window is displayed and is bound by the editor window.

MDI (mode)
          Multiple windows can be displayed, but the windows are bound within
          the editor window.

Detached (mode)
          Windows and toolbar are no longer limited to the main editor window.
          In Detached mode, the toolbar and windows "float"--and can be moved
          anywhere on the display.  The Control panel dialog box is also
          displayed, containing the buffer list and access information for open
          buffers.  Closing the Control Panel dialog box closes the editor.

One buffer per window
          Each buffer is assigned to a window, and each window is assigned a
          buffer.  A buffer may not be displayed in mulitple windows. This mode
          is only valid when Multiple or Detached is also selected.


ΓòÉΓòÉΓòÉ 5.5.2.2. Miscellaneous ΓòÉΓòÉΓòÉ

Use the Miscellaneous settings to specify general information for the current
window.  The table below describes each Miscellaneous window setting.

Vertical scroll bar
          Displays the vertical scroll bar.

Horizontal scroll bar
          Displays the horizontal scroll bar.

Display fully qualified path name on title bar
          Includes path informtion on the title bar.  If you don't select this
          check box, only the file name is displayed.

Line numbers
          Displays line numbers.  Use the line number "Format" field to specify
          a format for line numbers.

Format
          Enter a format for line numbers.


ΓòÉΓòÉΓòÉ 5.5.2.3. Visible strings ΓòÉΓòÉΓòÉ

Select the Visible strings tab to indicate how you want certain parts of the
text in your window to appear.  For example, you can specify certain characters
for use in displaying a tab stop, space, or virtual space.  Specifying these
options makes the text in your current buffer easier to read.  These characters
appear only in the window, and are not printed or saved in the file.

The following table describes each Visible strings setting.

Tab
          Inserts a string used to display a tab.

Space
          Inserts a character used to display a space.

Virtual space
          Inserts a character used to display a virtual space (space at the end
          of a line).

Newline
          Inserts a string used to display a virtual line (lines past the end
          of the buffer).

End of buffer
          Inserts a string used to display the end of the buffer.


ΓòÉΓòÉΓòÉ 5.5.2.4. Scrolling ΓòÉΓòÉΓòÉ

To specify the number of lines or columns to move when scrolling, click on the
Scrolling tab.  The table below describes each Scrolling setting.

Top
          Indicates the number of lines the cursor must be from the top of the
          window before the text will begin to scroll.

Bottom
          Indicates the number of lines the cursor must be from the bottom of
          the window before the text will begin to scroll.

Left
          Indicates the number of lines the cursor must be from the left edge
          of the window before the text will begin to scroll.

Right
          Indicates the number of lines the cursor must be from the right edge
          of the window before the text will begin to scroll.

Horizontal
          Indicates how many columns will scroll when the window scrolls
          horizontally.  For example, if the Right value is 3 and the
          Horizontal value is 5, when the cursor reaches the third column from
          the right of the screen, five new columns of text scroll into view.

Vertical
          Indicates how many lines will scroll when the window scrolls
          vertically. For example, if the Bottom value is 5 and the Vertical
          value is 7, when the cursor reaches the fifth line from the bottom of
          the screen, seven new lines of text scroll into view.

Scroll means pan
          If selected, the cursor stays in the same place on the screen while
          the text pans around it.  If cleared, the cursor stays in the same
          place in the text and moves with the text as you scroll.


ΓòÉΓòÉΓòÉ 5.5.3. Types Settings ΓòÉΓòÉΓòÉ

Use the Types Settings notebook pages to customize your files based on their
types.

There are two buttons at the bottom of each Types settings page:  Undo and
Default.  If you make changes on the page and want to return to the original
settings, click on Undo.  The settings specified prior to your changes (in the
current notebook) are displayed.  To change the settings to the editor's
default settings, click on Default.  The default settings are displayed.

Extensions

Compilers

Colors

Template


ΓòÉΓòÉΓòÉ 5.5.3.1. Extensions ΓòÉΓòÉΓòÉ

The Extensions page enables you to link extensions with types, as well as
add/delete extensions and types.  The list below describes each Extensions
setting.

Type
          Click on Add to add a new type to the list. (When a type is
          highlighted, the default compiler for that type is displayed.) To
          delete an existing type, highlight the type and click on Delete.  To
          copy a type's settings to another type, click on Copy and enter the
          type to be copied to.  To change a type's name, click on Change and
          enter the new name.

Enter extensions
          Enter the filename extensions associated with the selected type.  Any
          actions performed on the selected type will apply to all files whose
          extensions match the ones entered in the edit field.  Enter
          extensions as a space separated list.  For example: .c .cpp .h

Matching pairs
          Enter the symbols you want the editor to consider matching pairs.
          This string must be a space separated list of words in the form of
          "open1 close1 open2 close2...".  These matching pairs are used by the
          goto_matching() command (Find matching on the Search Menu), and the
          mark_matching() and mark_matching_next() menu items.


ΓòÉΓòÉΓòÉ 5.5.3.2. Compilers ΓòÉΓòÉΓòÉ

The Compilers page enables you to link types to compilers, and specify
information for executing a compile process.  The list below describes each
Compilers setting.

Type
          The type associated with the compiler.

Compiler
          Click on Add to add a new compiler to the list.  To modify an
          existing compiler, highlight the compiler and click on Change.  To
          delete an existing compiler from the list, highlight the compiler and
          click on Delete.  To create a new compiler based on the existing one,
          highlight the compiler to be copied and click on Copy.

Command line
          The command line and options for beginning a compile.

Error format
          Select the compiler with the error format you prefer.  Usually this
          will be identical to your compiler.  To provide your own error
          format, select "Other."

Other format
          If you select "Other" in the "Error format" field, you can customize
          your error format by adding codes to this field.  The error pattern
          is created from a superset of regular expression codes which indicate
          the order in which relevant information is displayed.

          Use the following macros to abbreviate information in your Compiler
          text fields:

   This macro... Means...

   $<        Full specification

   $r        Filename only

   $e        Extension (no period)

   $a        Current .AE file

   $p        Path only

          See also:

   o Advanced compiler settings


ΓòÉΓòÉΓòÉ 5.5.3.2.1. Advanced Compiler Settings ΓòÉΓòÉΓòÉ

The Advanced Compiler Settings dialog box allows you to configure how the
compiler executable runs.

Needs input Some compile processes require input from you during the compile
          (others can compile with just the information entered in the "Command
          line" field). Select this check box if your compile process will need
          input.

          You can leave the corresponding field blank, or you can enter a
          filename or a string prefixed with an equal sign (e.g. =y). Any
          characters in the file, or after the equal sign, will be passed to
          the compiler before any response entered in the compile output
          dialog.

List all output Lists raw output from compile, and not a parsed version.

Save all modified buffers Saves all loaded buffers that have been modified,
          rather than just the buffer being compiled.

Change to source directory Changes the directory where the file is loaded,
          before beginning the compile.

System flags Enables you to configure how you want to execute the compile.

Background Runs the compile asynchronously.  Control is returned immediately to
          the editor as the compile continues to run.

DOS settings Enables you to configure DOS compilers.  The DOS Settings push
          button is available.

Session   Runs the compiler in a separate session.  If this flag is set and the
          compiler is an OS/2 or DOS character mode program a command window is
          displayed when executing.  If this flag is not set for a character
          mode program the only output you will see is the results dialog box
          displayed by the editor. If the compiler is a PM program it is always
          run in a separate session and this flag has no effect.

Shell     Runs the compiler through a secondary command processor.  This is
          equivelant to performing the following command line from an OS/2
          prompt: cmd /c compiler.exe 'options'.

See also:

o DOS Settings


ΓòÉΓòÉΓòÉ 5.5.3.2.2. DOS Settings ΓòÉΓòÉΓòÉ

The DOS Settings dialog box allows you to configure your DOS compiler.  Click
on the OK button to save your changes or the Cancel button ignore your changes.

To add a new setting Type in your information in the setting and value fields
          then click on the add button to use the information.

To delete a setting Highlight the setting you want to delete and click on the
          delete button.

To change a setting Highlight the setting you want to change and type in a new
          value.

Setting   Enter the DOS Setting you want to configure.  You can use any DOS
          Setting that is available in the DOS Settings dialog box display in
          OS/2 for a DOS program. Some examples are:

   o DOS_AUTOEXEC.

   o DPMI_DOS_API.

Value     Enter the value for the DOS setting.  The value entered here will be
          specific to the setting entered in the setting field.


ΓòÉΓòÉΓòÉ 5.5.3.3. Colors ΓòÉΓòÉΓòÉ

The Colors page enables you to move beyond uniform foreground and background
colors with color syntax highlighting.  For each type, link categories and
related items to colors that make them easy to identify.

Because keywords and coding patterns are different for each type, those you
enter for one type will not apply to another.  For example, if you specify
colors for the "ada" type, and then change the type selection to "cobol", your
"ada" preferences are not listed.

Note: By default, color highlighting is on for all types.  To change this
setting for individual files or for types, specify your preferences on the
Buffer flags page in the Buffer settings notebook.

Refer to the sections below for complete descriptions for elements of the
Colors page.

Type
          Before you begin specifying colors for categories and items, select
          the Type associated with your file.  "Type" indicates an association
          between the test string and related file extensions.  The color
          settings you specify are applied only to the Type selected.

Escape character
          Character used when a line style is set as escapable (see Advanced
          items to see how to make a line style escapable).  When the Escape
          character precedes an escapable line style then that style will not
          be considered for color highlighting.  For example if you have "
          "(two double quotes) configured as an escapable line style then the
          following string would not be color highlighted:  \"this is not color
          highlighted\"

Keyword delimiter
          Enter characters used to delimit, or mark the boundaries for, keyword
          items.  Keywords will only be highlighted if they are surrounded by
          spaces or keyword delimiters.

Category
          This scope box enables you to add, delete, and change colors for
          categories.  When you change a category color, all the items that
          belong to that category also change.  Use the table below for
          instructions on completing these activities.

                    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                    ΓöéTo...               ΓöéPerform this action...                            Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéAdd a category      ΓöéClick on the Add button.  A dialog box is         Γöé
                    Γöé                    Γöédisplayed in which you can enter the category nameΓöé
                    Γöé                    Γöéand select colors.                                Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéDelete a category   ΓöéHighlight the category in the list box and click  Γöé
                    Γöé                    Γöéon Delete.                                        Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéChange a category's ΓöéHighlight the category in the list box and click  Γöé
                    Γöécolors              Γöéon the Category Color button.  The Select Syntax  Γöé
                    Γöé                    ΓöéColor dialog box is displayed.  Select the new    Γöé
                    Γöé                    Γöécolors and click on Done.                         Γöé
                    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Item
          The Item scope box enables you to add, delete, and change colors for
          items within the selected category.  Use the table below for
          instructions on completing these activities.

                    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                    ΓöéTo...               ΓöéPerform this action...                            Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéAdd an item         ΓöéClick on the Add button.  The Create New Item or  Γöé
                    Γöé                    ΓöéCategory dialog box is displayed. Enter the item  Γöé
                    Γöé                    Γöéname, select the colors for the item, and click onΓöé
                    Γöé                    ΓöéDone.                                             Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéDelete an item      ΓöéHighlight the item and click on the Delete button.Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéChange an item's    ΓöéHighlight the item and click on the Item color    Γöé
                    Γöécolors              Γöébutton.  The Select Syntax Color dialog box is    Γöé
                    Γöé                    Γöédisplayed with color options.  Select the new     Γöé
                    Γöé                    Γöécolors and click on Done.  Note: Beginning/ending Γöé
                    Γöé                    Γöéitems must be entered as one item, separated by   Γöé
                    Γöé                    Γöéspaces.  For example: /* */                       Γöé
                    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Style
          The Style scope box enables you to select the style of your item.
          Only the styles that might apply to the item are enabled.  The
          following table describes the Style options available to you.

                    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
                    ΓöéStyle     ΓöéDescription                                                 Γöé
                    ΓöéOption    Γöé                                                            Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéKeyword   ΓöéHighlights the item when it exists between two keyword      Γöé
                    Γöé          Γöédelimiters. (Space is a default delimiter.)                 Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéLine      ΓöéHighlights the item and all text between.  If no ending itemΓöé
                    Γöé          Γöéis specified, then all text to the end of the line is       Γöé
                    Γöé          Γöéhighlighted.  The editor will not highlight more than one   Γöé
                    Γöé          Γöéline whether the ending marker is found or not.  Lines have Γöé
                    Γöé          Γöéadvanced features associated with them.                     Γöé
                    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
                    ΓöéBlock     ΓöéHighlights the item and all text between.  Blocks can span  Γöé
                    Γöé          Γöémultiple lines and always continue highlighting up to the   Γöé
                    Γöé          Γöéend marker.  Note: Blocks cannot have identical beginning   Γöé
                    Γöé          Γöéand ending items.                                           Γöé
                    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

See also:

o Advanced items
o Select Syntax Color
o Create New Category or Item


ΓòÉΓòÉΓòÉ 5.5.3.3.1. Advanced items ΓòÉΓòÉΓòÉ

The Advanced Items dialog box is available for Line style items.  Here you can
specify an escape character which denotes that this character is escapable.
You can also specifiy that the line style is only valid if it starts in a
specific column.  The options on this dialog box are mutually exclusive.  For
instance, you cannot specify a line style is escapable and must start in a
specific column.

Example: In the C programming language, programmers often escape the " (quote)
character.

In the COBOL programming language, the comment character appears in a specific
column where it must be recognized.  This character is considered valid if
found in a column specified by you in the Advanced Item dialog box.

____________

See also:

o Colors


ΓòÉΓòÉΓòÉ 5.5.3.3.2. Select Syntax Color ΓòÉΓòÉΓòÉ

The Select Syntax Color dialog box allows you to change the color setting for
any existing item or category. Select one or more items or categories from the
list box displayed and then select the desired foreground and background colors
to apply to the selected items. If you wish to use your window foreground or
background color for any item check the appropriate Use Default check box. When
you are finished click the Done button. Click on the Custom button to change
what color is displayed in one of the 16 foreground or background color boxes.

____________

See also:

o Configure Color
o Colors


ΓòÉΓòÉΓòÉ 5.5.3.3.3. Create New Category or Item ΓòÉΓòÉΓòÉ

The Create New Item or Category dialog box allows you to add a new item or
category to the type selected on the Colors notebook page. To add a new item:

 1. Fill in the edit field with the name of the new item or category.

 2. Optionally click on the Custom button to change one or more of the colors
    displayed.

 3. Optionally change the colors assigned to the new item.

 4. If you want to add another item click on the Add button and go back to step
    1. If you don't want to add another item click on the Done button. Your
    current item will be added and the dialog box will go away.

____________

See also:

o Configure Color
o Colors


ΓòÉΓòÉΓòÉ 5.5.3.3.4. Configure Color ΓòÉΓòÉΓòÉ

The Configure Color dialog box allows you to change one of the 16 foreground or
background color boxes displayed on the Select Syntax Color dialog box. To
change a color simply configure the RGB (red, green, blue) values for the
foreground or background color. The sample text will display with the colors
you have configured.  When you are satisfied with your changes click on the OK
button.

____________

See also:

o Colors
o Create New Category or Item
o Select Syntax Color


ΓòÉΓòÉΓòÉ 5.5.3.4. Template ΓòÉΓòÉΓòÉ

The Template page enables you to link a type with a template.  The list below
describes each Template option.

Type
          The type associated with the template.

Template
          Use the selection box to choose the language template to associate
          with the selected extension.

Template expansion
          Enables template expansion.


ΓòÉΓòÉΓòÉ 5.5.4. Buffer Settings ΓòÉΓòÉΓòÉ

Select the Buffer tab to define buffer-specific settings. You can change Buffer
settings for a single buffer, all buffers of a specific type, or set your
default buffer settings.

 There are two additional buttons at the bottom of each Buffer settings page:
Undo and Default.  If you make changes on the page and want to return to the
original settings, click on Undo.  The settings specified prior to your changes
(in the current notebook) are displayed.  To change the settings to the
editor's default settings, click on Default.  The default settings are
displayed.

To tailor global editor settings, see the section titled Editor Settings  To
customize window settings, see the section titled Window Settings

Buffer flags

Miscellaneous

Word processing


ΓòÉΓòÉΓòÉ 5.5.4.1. Buffer flags ΓòÉΓòÉΓòÉ

Select the Buffer flags tab to specify common buffer settings for each type or
just the current buffer.  The table below describes each Buffer flags setting.

Current buffer
          All settings you specify will apply only to the current buffer.

Default
          The settings you specify will become the new default settings.

Type
          All settings you specify will apply only to the type selected.

Real space only
          The cursor is forced to stay in real space, meaning that it is not
          permitted to move beyond the end of the line.

Tabs to spaces
          Pressing Tab inserts spaces rather than tabs.

Read only buffer
          The current buffer window is designated as read only.  The read only
          indicator (RO) may appear in the status bar. (See Status Bar options
          in the Editor Settings to toggle this on and off.)

Color highlight
          Enables color syntax highlighting.

Snap to EOL
          If characters are typed in virtual space, they are "snapped" (moved
          back) to the end of the current line.

Expand tabs
          When the file is saved, all tabs are converted to spaces.

Overtype mode
          Newly-typed characters are typed over the top of existing text,
          replacing it. Otherwise, newly-typed characters are inserted without
          effecting existing text.

Apply to all Types
          Applies the specified settings to all currently defined types.
          Otherwise, new settings are applied only to the currently selected
          type.


ΓòÉΓòÉΓòÉ 5.5.4.2. Miscellaneous ΓòÉΓòÉΓòÉ

Use the Miscellaneous settings to tailor the tabs and other various features.
Use the Extensions page of the notebook to override these settings for specific
extensions.

For more information about each Miscellaneous buffer setting, refer to the
following table.

Current buffer
          All settings you specify will apply only to the current buffer.

Default
          The settings you specify will apply only to the type selected.

Type
          All settings you specify will apply only to the type selected..

Tab stops
          Enter the column positions to be used as tab stops.  Implicit tab
          stops are calculated using the distance between the last two
          specified tabs.

Auto indent mode
          Select this check box to enable auto indent. Clear this check box to
          disable auto indent mode.

Apply to all Types
          Applies the specified settings to all currently defined types.
          Otherwise, new settings are applied only to the currently selected
          type.


ΓòÉΓòÉΓòÉ 5.5.4.3. Word processing ΓòÉΓòÉΓòÉ

Current buffer
          All settings you specify will apply only to the current buffer.

Default
          The settings you specify will apply only to the type selected.

Type
          All settings you specify will apply only to the type selected..

Word processing enabled
          Word processing is enabled and word wrap occurs.

Auto flow
          Wraps paragraph when you add new text to a line of an existing
          paragraph. (If you do not enable autoflow, new text will not wrap
          unless you execute wrap_paragraph())  Word processing must be enabled
          for autoflow to work.

Copy left margin text
          If your left margin is set to a value greater than zero, the
          characters in the columns preceding the left margin are copied to the
          beginning of the new line when you press [Enter].  This feature is
          especially useful when you write comment blocks.

Left margin
          The column number where the left margin begins.

Right margin
          The column number for the right margin.

Apply to all Types
          Applies the specified settings to all currently defined types.
          Otherwise, new settings are applied only to the currently selected
          type.


ΓòÉΓòÉΓòÉ 5.5.5. File Settings ΓòÉΓòÉΓòÉ

Notebook pages in the File Settings topic section enable you to specify how you
want the editor to handle files.  In this section, you can specify file access
and how windows work with files.

There are two buttons at the bottom of each File settings page: Undo and
Default.  If you make changes on the page and want to return to the original
settings, click on Undo.  The settings specified prior to your changes (in the
current notebook) are displayed.  To change the settings to the editor's
default settings, click on Default.  The default settings are displayed.


ΓòÉΓòÉΓòÉ 5.5.5.1. Access ΓòÉΓòÉΓòÉ

Use the Access settings to specify how the editor handles your LAN files,
Floppy files, and/or Local files.  Each Access setting is described in the
following table.

File type
          The type of files you want the Access settings to apply to.

Copy to memory
          Copies the file to virtual memory.  You can specify for the editor to
          make this copy when you begin to modify, when you open the file, or
          not to copy the file. If "Do not copy" is selected, the editor will
          re-read the original file when needed.

Lock files on modification
          Locks access to other users when you begin to modify a file.


ΓòÉΓòÉΓòÉ 5.5.6. Quick Settings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.5.6.1. Editor Quick Settings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.5.6.2. Window Quick Settings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.5.6.3. Types Quick Settings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.5.6.4. Buffer Quick Settings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.6. Colors ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.7. Fonts ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.8. Key bindings ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.9. Toolbar ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.10. Statusbar ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6. Configuring ΓòÉΓòÉΓòÉ

When you load the editor, it executes the startup() function, which:

o Executes the functions in the LANGUAGE.PEL file

o Executes the localj_setup() command (in the LOCAL.PEL file).

o Reads the CPE.CFG file (configuration file)

o Executes the local_settings() command (in the LOCAL.PEL file).

Initialization follows the order shown above.  If the same settings is
specified more than once, the editor uses the last instance read.

Refer to the following sections for a description of each initialization step
and how you can configure these steps to include your preferences.

o LANGUAGE.PEL
o local_setup()
o CPE.CFG
o local_settings()
o local_keys()
o Configuration Examples


ΓòÉΓòÉΓòÉ 6.1. LANGUAGE.PEL ΓòÉΓòÉΓòÉ

The functions in the LANGUAGE.PEL file are the first executed during
initialization. LANGUAGE.PEL contains type-related information you specify in
the Settings notebook.  Each time you make changes to the the Settings
notebook, the editor recompiles LANGUAGE.PEL and immediately recognizes your
changes.

Caution: Because all settings associated with types are specified in this file,
YOU SHOULD NOT CHANGE LANGUAGE.PEL MANUALLY.


ΓòÉΓòÉΓòÉ 6.2. local_setup() ΓòÉΓòÉΓòÉ

Use the local_setup() function to specify settings that will not change often.
This function is located in the LOCAL.PEL file.

See also:

o local_setup()


ΓòÉΓòÉΓòÉ 6.3. CPE.CFG ΓòÉΓòÉΓòÉ

This file stores your options that are likely to change often.  Because the
CPE.CFG file does not have to be recompiled to implement changes, you can
change options stored here and the editor will recognize these changes the next
time it is started. Notebook settings and the state of the editor are also
stored in the CPE.CFG file.

The CPE.CFG file is similar to your AUTOEXEC.BAT file or CONFIG.SYS file, in
that it initiates settings and performs tasks you want completed every time you
start PREDITOR/2.


ΓòÉΓòÉΓòÉ 6.4. local_settings() ΓòÉΓòÉΓòÉ

The local_settings() function is called after the editor executes statements in
the CPE.CFG file. Here, you can specify options that override those stated in
the CPE.CFG file.

For example, you may want to save all but one of your settings when you exit.
To do this, select the "Save settings on exit" option on the Save subtopic page
in the Editor Settings notebook.  Then, specify the setting that should not be
saved in local_settings().  The local_settings() function is also a good
location to place your own PEL that needs to be initialized after CPE.CFG.


ΓòÉΓòÉΓòÉ 6.5. local_keys() ΓòÉΓòÉΓòÉ

The local_keys() function is called whenever you change an emulation and is set
either in the CPE.CFG file or in local_settings().  The advantage of specifying
key assignments in local_keys() is if you change emulations during an editor
session, your customized key assignments will be maintained.

For example, you may set the emulation in any or all of local_setup(), CPE.CFG,
and local_settings(). Each time the emulation changes, local_keys() is called
and your customized key assignments are available to you.


ΓòÉΓòÉΓòÉ 6.6. Modifying LOCAL.PEL ΓòÉΓòÉΓòÉ

You must decide if you will use the configuration file (CPE.CFG) or the
LOCAL.PEL file for your options.  We recommend that you use the LOCAL.PEL file
because it keeps startup time at a minimum.  A lengthy configuration file
increases startup time.

To modify functions in LOCAL.PEL,

 1. Open the C:\CPE\PEL\LOCAL.PEL file.

 2. Edit the file to include your preferred options. If you are adding new
    options, look for the comment # All other custom initialization goes here
    and place options after this comment.


ΓòÉΓòÉΓòÉ 6.6.1. Predefined User Options ΓòÉΓòÉΓòÉ

The LOCAL.PEL file is preset to contain many of the user options you might want
to set.  These options are easy to activate.

The table below describes some of the options that are predefined in the
local_setup() function in LOCAL.PEL.

autosave( n )
          Saves the file automatically after n seconds of inactivity. The
          default is 0 (disabled).

save_state = 1Enables saving information about the editor state in the
configuration file.  This slows the loading process, but enables youto resume
where you left off.

set_default_buffer_flag (BUFFER_EXPAND_TABS, 1)
          Converts tabs to spaces on writes for all subsequent buffers.

set_default_buffer_flag (BUFFER_OVERTYPE_MODE,0)
          Makes inert mode the default for all subsequent buffers.

set_default_buffer_flag (BUFFER_SNAP_TO_EOL,0)
          Enables insertion of text past the end of the line.

set_default_buffer_flag (BUFFER_TABS_TO_SPACES, 0)
          Disables conversion of tabs to spaces as you type.

toggle_auto_indent(0)
          New lines are not automatically indented to previous level.

toggle_electric(0)
          Turns off electric C "code processing mode" (language templates and
          so on).

toggle_file_backup(0)
          Makes no backup copy of modified files.

toggle_pvcs(0)
          Set to 3 to have PREDITOR/2 prompt you to retrieve a file from a PVCS
          log file if that file does not exist or is read-only.

To activate predefined user options in the LOCAL.PEL  file,

 1. Locate the option you want to activate and remove the comment character (#)
    from the beginning of the text line.  At this time, you might also choose
    to change the options' values.

 2. Recompile LOCAL.PEL.

Note: PREDITOR/2 processes the local_setup() function before reading CPE.CFG.
Options set in local_setup() may be reset or overridden by options in the
CPE.CFG file.  A common problem arises from first setting the emulation mode
through the notebook and also by changing local_setup().

To modify CPE.CFG,

 1. Open the C:\CPE\CPE.CFG file and locate the section stating $USER SETTINGS$
    # Place user settings here.

 2. Edit the file at this location and save your changes.

When using the CPE.CFG file, the order in which your options are executed is
important.

Note: The initial loading of PREDITOR/2 may be slowed down if you store too
many options in the CPE.CFG file.  Therefore, use the LOCAL.PEL file to select
options that are not likely to change often.


ΓòÉΓòÉΓòÉ 6.7. Moving Options Between Files ΓòÉΓòÉΓòÉ

To reduce startup time or to put long function calls elsewhere, move
appropriate options from CPE.CFG to LOCAL.PEL file.  (For example, rather than
defining key assignments with the emulation in CPE.CFG, move these to the
local_keys() portion of LOCAL.PEL.)

To move options from CPE.CFG to LOCAL.PEL,

 1. Edit the CPE.CFG file and the LOCAL.PEL file in the PEL subdirectory.

 2. Select and cut the lines in CPE.CFG, in the $USER_SETTINGS$ section.

 3. Switch to LOCAL.PEL and paste the lines after the line # other custom
    initialization or keymap definitions can go here... in the function
    local_setup().

    Note: If you copied a line containing your emulation mode (i.e., Brief,
    CUA, etc.) into local_setup(), delete it.

 4. Locate the line containing your emulation (earlier in local_setup()) and
    remove the comment character (#).  This decreases the chance of your
    specifying options out of order in the future.

    For example, if you work in the Emacs emulation, remove the comment
    character on the corresponding line, as shown below:

   # cua()

   # native()

   # vi()

   # brief()

   emacs()

   # ispf()

All the variable assignments (i.e., lines containing an equal sign) you placed
in your LOCAL.PEL file need no further modifications.  However, the remaining
lines (if any) are function calls and need to have parentheses and commas
placed appropriately.

 5. Place parentheses and commas in remaining function calls and commas between
    arguments.  An opening parenthesis belongs after the first word on the line
    and a closing parenthesis goes at the end of the line.  Commas belong after
    each argument falling between.  For example:

    set_default_buffer_flag( BUFFER_READ_ONLY, 1 )

 6. Recompile LOCAL.PEL.


ΓòÉΓòÉΓòÉ 6.8. Configuration Examples ΓòÉΓòÉΓòÉ

The following sections show examples of how you can make additions and changes
to the LOCAL.PEL file. Changes you make may require you to use functions and
variables from the Professional Extension Language (PEL).  For further
information on PEL, see Programming with PEL.

Assigning Keys

Your emulation is defined in the CPE.CFG file.  This emulation has a standard
list of key assignments that apply to your emulation.  To change the keystrokes
used for various activities, place them in the local_keys() function.  These
key assignments will override the standard emulation key assignments that are
defined in CPE.CFG.

For example:

global function local_keys()
{
   assign_key( "<Alt-Num-5>", "set_line_mark")
   assign_key( "<Num-5>", "set_inclusive_mark")
   assign_key( "<Ctrl-Num-5>", "set_column_mark")
   assign_key( "<Alt-Num-+>", "next_buffer")
   assign_key( "<Ctrl-1>", "goto_bookmark 1")
   assign_key( "<Ctrl-2>", "goto_bookmark 2")
   assign_key( "<Ctrl-3>", "goto_bookmark 3")
   assign_key( "<Ctrl-4>", "goto_bookmark 4")
   assign_key( "<Ctrl-5>", "goto_bookmark 5")
   assign_key( "<Ctrl-6>", "goto_bookmark 6")
   assign_key( "<Ctrl-7>", "goto_bookmark 7")
   assign_key( "<Ctrl-8>", "goto_bookmark 8")
   assign_key( "<Ctrl-9>", "goto_bookmark 9")
   assign_key( "<Ctrl-0>", "goto_bookmark 10")
   assign_key( "<Ctrl-Num-+>", "append_to_scrap")
}

Setting the Default Directory

To have the editor automatically default to the same directory upon startup,
specify the default file path in local_setup().

For example:

global local_setup()
{
   chdir( "c:\\mydirect" )
}

Adding or Modifying an Emulation

PREDITOR/2 provides emulations of some popular editors available on the market
today because many users have become familiar with the keymapping activities
associated with these emulations. You can modify these emulations, or add your
own to further configure the editor to your programming style.

To modify an existing emulation, you can either

 1. Make changes in LOCAL.PEL (we recommend that you do this in the
    local_keys() function).

    or

 2. Make changes in the emulation, which is defined in the .PEL emulation files
    (e.g. BRIEF.PEL, CUA.PEL, EMACS.PEL).

Caution: If you choose to make changes to the .PEL emulation files, you risk
irreparably changing an emulation and losing the initial emulation. We
recommend that you modify emulations in LOCAL.PEL.

To add your own emulation,

 1. Open the MY_MODE.PEL file, which is located in the PEL directory.

 2. Select Save as from the File menu and save the file as your new emulation.
    For example, NEW_MODE.PEL.

 3. Modify this file to include your emulation preferences.

 4. Compile and run your new file.

    Note: Refer to the .PEL emulation files (e.g. BRIEF.PEL, CUA.PEL,
    EMACS.PEL) for examples on setting up your own emulation.


ΓòÉΓòÉΓòÉ 7. Programming with PEL ΓòÉΓòÉΓòÉ

For customers who want more, Compuware has taken the unusual step of providing
access to most of PREDITOR/2's own source code, so you can personalize existing
features to your liking and create new options.  The Professional Extension
Language (PEL) is the piece of PREDITOR/2 that truly makes this editor unique.
You can use PEL to make your editor work according to the way you do.

The sections listed below discuss the basic features of the Professional
Extension Language (PEL) and contrasts them with other programming languages.
Here, we assume that you are familiar with elementary programming concepts.

Note: Non-programmers can learn basic programming concepts from "The AWK
Programming Language" by Aho, Weinberger, and Kernighan.

Short course in PEL

A Closer Look at PEL

Writing a PEL function

PEL Compiler

PEL Debugger

Type Identifiers

Functions

Variable types


ΓòÉΓòÉΓòÉ 7.1. Short Course in PEL ΓòÉΓòÉΓòÉ

The first step in learning to program in PEL is to understand how to read
source code written for it. The following sample PEL code is explained in this
section.

#----------------------------------------------------#
#                                                    #
# Functions to support special calls                 #
#                                                    #
#----------------------------------------------------#

global recordString = ""

# For assignment to key
global function playitback()
{
   if (playback(recordString) == 0)
      beep();  # Beep on error
}

# For assignment to key
global function recordit()
{
   # Note that assignments are allowed in "if"
   if (recordString = record())
      message("Recording completed.")

   else   # Semicolons are optional
      message("Recording keystrokes.")
}

global function write_current_block( file name )
{
   if (selection_type() != 0)
      return write_marked_block( file name )

   else
      return write_buffer( file name )
}
 The sample above contains the following:

Comments

Variable declarations

Functions


ΓòÉΓòÉΓòÉ 7.1.1. Comments ΓòÉΓòÉΓòÉ

PEL uses the pound sign (#) as its comment character.  Whenever you place the
comment character within a line, the PEL compiler ignores the text from that
point to the end of the line.

The comments in the previous example are:

# For assignment to key
# Beep on error
# For assignment to key
# Note that assignments are allowed in "if"
# Semicolons are optional


ΓòÉΓòÉΓòÉ 7.1.2. Variable Declarations ΓòÉΓòÉΓòÉ

Following the comment block in the example above, is an optional variable
declaration: global recordString = ""

For PREDITOR/2 we recommend that you declare variables before using them
(although this is not required).  This ensures that the scope of the variable
is as you intend, and it provides a basis for identifying typographical errors.


ΓòÉΓòÉΓòÉ 7.1.2.1. Global Variables ΓòÉΓòÉΓòÉ

The variable declared in the above example is recordString.  The variables used
in PEL are case sensitive; therefore the upper case S in this variable
declaration is significant.  The word global, which appears at the beginning of
the line, determines the scope of the variable.  As a global variable, any
function in this file or any other file that is compiled with it may use this
variable.


ΓòÉΓòÉΓòÉ 7.1.2.2. Local Variables ΓòÉΓòÉΓòÉ

PEL also supports local variables whose declarations begin with the word local.
Local variables that you declare outside of a function are local to that file.
You cannot reference these variables from other files.  However, because they
are static variables, they retain values assigned to them between calls to the
module.


ΓòÉΓòÉΓòÉ 7.1.2.3. Variable Types ΓòÉΓòÉΓòÉ

Notice that the type of variable being declared is not specified.  This is
because PEL variables are not assigned a type.  Any PEL variable can hold
either a string or a long integer.  No floating point variables are supported
in PEL.  A PEL variable may also be an array used to hold either a string, a
long integer, or both.  A variable becomes an array when it is referenced with
a subscript in the program.  Since these variables are not declared by type,
you may want to signify the intended type in the variable name.  The
recordString variable (shown in the example above) illustrates this approach.
You can also identify arrays in a similar manner.

You can initialize variables to a value when declaring them.  This is done
using the same syntax as used to make an assignment to a variable within a
function.  A semicolon at the end of the declaration is optional.


ΓòÉΓòÉΓòÉ 7.1.3. Functions ΓòÉΓòÉΓòÉ

The three functions in the above example are shown in a commonly-used format:

function function_name(<untyped arguments>)
{
   statements
}

Each function begins with the word function.  Like variables, functions may
also be local to the module.  By default, however, they are global.  If you
want to make a function local, precede the word function with local.

The function name is always followed by open and closed parentheses, even if
the function doesn't take any arguments.  There must be no intervening space
between the function name and the open parenthesis.  If the function requires
one or more arguments, they are specified between these parentheses.  PEL
requires only a list of these arguments separated by commas, without any
mention of their type.  You can add definitions to these arguments by giving
them names that reflect their intended use.


ΓòÉΓòÉΓòÉ 7.1.3.1. Statements ΓòÉΓòÉΓòÉ

The statements within a function perform the task assigned to the function.
You can terminate statements with a semicolon if you want.  One benefit of this
is that if you are used to putting a semicolon after the first statement in an
if..else construct, it will not be regarded as a syntax error.  However, if
more than one statement appears on a line, a separating semicolon is required.


ΓòÉΓòÉΓòÉ 7.1.3.2. Value Returned ΓòÉΓòÉΓòÉ

All functions return a value, and you can either use this value or ignore it.
Therefore the following syntax example is permissible:

return_value = my_function()

The usefulness of the value returned from the function is determined by the way
the function has been written.  The first two functions in the PEL code example
do not explicitly return a value.  As noted in the comments associated with
these two functions, the functions are intended for assignment to a key.  When
PREDITOR/2 executes a function as a result of a key assignment, it ignores any
value returned by the function.  For this reason, there is no point in
explicitly returning a value if the function is only executed by pressing its
assigned key.

Note: Since the values returned by functions assigned to a key are not
scrutinized, errors may go undetected unless the function itself calls
attention to the error.  This may be done by displaying a message or by issuing
a beep().  The first two example functions show how this might be done.

When you want to explicitly return a value from a function, precede the value
(or the function call that returns the value) with the keyword return.  If the
value you want to return is itself a value returned to your function by another
function, you can prefix the call to that function with the keyword return.
This is illustrated in the write_current_block() function in the PEL code
example:

return write_buffer()

The write_current_block() function also demonstrates that you can use the
return keyword more than once within a single function.  This gives the
function more than one exit point.


ΓòÉΓòÉΓòÉ 7.1.4. Automatic Variables ΓòÉΓòÉΓòÉ

Functions may also contain local variables.  These are called automatic
variables and are declared in the same manner as local variables defined
outside of functions:

function my_function()
{

   local index # Example automatic var.
   statements

}

The scope of an automatic variable is limited to the function in which it is
declared.  The variable is unknown outside the function.


ΓòÉΓòÉΓòÉ 7.1.4.1. Naming Automatic Variables ΓòÉΓòÉΓòÉ

If an automatic variable has the same name as a global or local variable, only
the automatic variable is accessible from within the function.  In the
automatic variable example above, there may also be a global variable named
index.  Any references to a variable named index within the function always
apply to the automatic variable.


ΓòÉΓòÉΓòÉ 7.1.5. Control Structures ΓòÉΓòÉΓòÉ

The earlier function examples show various forms of the if and if..else control
structures.  The form for this control structure is the same as that in the C
programming language.  PEL also shares several other control structures with C.
PEL supports the for, while and do..while structures.  The following examples
illustrates some of these control structures.

Control structures, examples

Control structures, return value


ΓòÉΓòÉΓòÉ 7.1.5.1. Examples ΓòÉΓòÉΓòÉ

Example 1:

global function standardKeys()
{

   local i = 0
   for (i = 1; i <= 255; i++)
   assign_key(chr(i),"insert_key")

}

Here, we use a for loop to assign all but the extended keystrokes to their
proper key.  This function is useful for entering assignments into a new
keymap.

Example 2:

global function readKey()
{

   while (!keyboard_input_pending)
   ; # do nothing.
   return getkey()

}

This control structure function uses a while loop to build a replacement for
the getchar() function. This function waits until keyboard input is pending. It
then uses getkey() to return the scan code with the ASCII value.  The getchar()
function serves a similar purpose but does not provide a scan code.

Example 3:

global function select(promptStr, keyStr)
{ local ch

   local ok

   message(promptStr)

   keyStr = toupper( keyStr )

   do

   { ch = toupper( chr(getchar()) )

      if ( !(ok = cindex(keyStr,ch)) )

      beep()

   } while ( !ok )

   return ch

}

This example is more complex.  It prompts for input and then uses a do..while
loop to read the keyboard repeatedly until it receives an acceptable response.
It then returns that response to the calling function.  (The confirm() function
also performs this function.)


ΓòÉΓòÉΓòÉ 7.1.5.2. Return Value Conventions ΓòÉΓòÉΓòÉ

All functions return a value.  For purposes of controlling the program's flow,
the extension language treats all values other than zero as TRUE.  A value of
zero or an empty string is treated as FALSE.  PREDITOR/2's library functions
associate returning TRUE with success and FALSE with failure (whenever
applicable).  This means that most functions in the library return a non-zero
value when successful and a zero value upon failure. The exceptions to this
convention are primarily those functions that cannot fail or do not return. In
addition, some functions return 0 as a meaningful value, such as length(),
which reports the length of a string.  A string length of 0 is a meaningful
value rather than an error.  Such a function is in no danger of failing, so we
do not need a method of testing for failure.  Functions for which 0 (zero) is a
meaningful return value that also may need to report failure, do so by
returning -1.  The latter are generally file input and output functions such as
fread() and fwrite().

PREDITOR/2's function library uses the above return value conventions to allow
control of program flow. In this way, you can code all operations that could
fail as follows:

if ( operation(args) )
{

   code to use upon success

}
else
{

   code to handle failure

}

All library functions for which it is reasonable to test for success follow
this convention.  The few that do not follow this behavior are clearly labeled
as such in their function definition.  We recommend that you follow this
convention in writing your functions.  See the Truth Values section for a
further discussion of true/false values.

Note: If you neglect to return a value from a function, it will always return a
zero (FALSE) value.  If you later use this function in a control structure such
as the one shown above, it will always appear to fail.


ΓòÉΓòÉΓòÉ 7.2. A Closer Look at PEL ΓòÉΓòÉΓòÉ

PREDITOR/2's configurability lies largely with its extension language, PEL.
Therefore, if you do not like the way it currently operates, you have the
option of creating a new function or changing an existing function to your
specifications.  This section describes the fundamental concepts behind PEL.


ΓòÉΓòÉΓòÉ 7.2.1. Variable Declaration Syntax ΓòÉΓòÉΓòÉ

PEL variable declaration statements can take either of the following two
formats, depending on their scope:

local <decl> [, <decl>... ][;]
global <decl> [, <decl>... ][;]

The keyword local or global indicates the scope of the variable(s) declared.
Only local variables may be declared inside of functions.  When variables
identified as local are declared outside of functions, they are static in
nature.  Declared within a function, they are automatic. The keyword defining
scope is followed by one or more declarations (shown as <decl> in the formats
above), separated by commas and optionally terminated with a semicolon.  The
variables declared may be string or integer, or mixed.

The format of the individual declarations is:

<variable name> [= <expression>]

The variable name can be any combination of letters, numbers, and underscores,
as long as it does not begin with a number.  The case used in this variable
name declaration is significant.  The variable can be initialized to the value
of some expression.  See the Statements section for a discussion of the
contents of expressions.  If a variable is not explicitly initialized, it is
automatically initialized to zero or an empty string, depending upon its usage.
Variables can be initialized to values other than constants, such as other
variables or the return value of a function.  All variables that are
initialized to a constant value, however, are initialized first.

Note: To avoid confusion and to guarantee forward compatibility, we recommend
that only variables local to a function be initialized to values other than
constant.


ΓòÉΓòÉΓòÉ 7.2.2. Naming Variables ΓòÉΓòÉΓòÉ

You can define local variables with the same name as global variables, and
local functions with the same name as global functions.  You can even have
local functions with the same names as global variables. However, you can not
have a global function and a global variable with the same name.

When both a global and local variable or function have been defined using the
same name, references apply to the one that is most local in scope.  The
example below, containing three declarations of the variable foo, illustrates
this rule:

global  foo = 11
local  foo = 22
function nonesuch() {

   local foo = 33
   message("foo=" foo)

}

When the nonesuch() function is called, it prints the message "foo=33".  If the
local declaration of the foo variable found within the nonesuch() function is
removed, the message becomes "foo=22". If the foo declaration local to the
module is also removed, it becomes "foo=11".

Under most circumstances, it is undesirable to give the same name to local and
global variables, as this limits access to the variable with broader scope.


ΓòÉΓòÉΓòÉ 7.2.3. Undeclared and External Variables ΓòÉΓòÉΓòÉ

PEL does not require that you declare variables before using them.  On the
other hand, if you don't declare variables, you will lose control of their
scope.  Using variables without declaring them causes them to be local to the
module in which they are used.

We recommend that you declare and initialize all variables you plan to use.
This will help you keep track of where variables are being defined and where
they are being referenced.  This method gives you the maximum amount of control
while ensuring minimal confusion.  The strict declarations compiler option also
helps you keep variables in order.  See the PEL Compiler for a discussion of
this option.


ΓòÉΓòÉΓòÉ 7.2.4. Arrays ΓòÉΓòÉΓòÉ

AWK and PEL support a special type of array called an associative array.  These
differ from arrays in C, Pascal, and many other languages in that they may use
strings as subscripts to reference members of the array.  This means that
arrays may be indexed with any of the following subscripts:

myarray[1]
myarray[21]
myarray["two"]
myarray["Dan"]
myarray["David"]

There is no difference between the way an array is declared and the way
ordinary variables are declared.  The number of elements may not be specified
and need not be known.  The appearance of a subscript (square brackets
containing a value) following a variable signals PEL that the variable is an
array.  In other words, all you have to do to create an array is to begin using
it in your program.

There are special operators for use with arrays, such as the in operator, which
tests for membership. See the "Array Operators" section later in this chapter
for further information on this topic. Standard AWK does not support
multidimensional arrays but allows their simulation.  PEL supports
two-dimensional arrays.


ΓòÉΓòÉΓòÉ 7.2.5. Function Syntax ΓòÉΓòÉΓòÉ

A function declaration uses the following syntax:

[local | global] function <name>(<argument list>)
{

   [local variable declarations]
   <statements>

}


ΓòÉΓòÉΓòÉ 7.2.6. Guidelines and Reminders ΓòÉΓòÉΓòÉ

The following guidelines apply to function syntax:

o Begin functions with either the local or global keyword.  If you do not
  specify the scope, the default is global.

o Precede the function name with the keyword function.

o Do not begin function names with a number.

o Place arguments required by a function after the function name and enclosed
  in parentheses ( () ).

o Separate argument names with a comma ( , ).

o Do not specify argument types.

o Do not add a space between the function name and the open parenthesis in
  either function declarations or function calls. (Intervening space causes a
  syntax error in declarations, and is mistaken for string concatenation in
  function calls.)

o Enclose the statements that comprise the function in curly braces ({}).

o Declare local (PEL) variables at the beginning of a function;  variables
  cannot be declared anywhere else in a function.

Reminders

All arguments in the argument list are optional. Be careful when passing
numbers.  As a safeguard, you should add 0 to all arguments that should be a
number within the number.  For example:

pass_a_number(anum+0).

Function names are case-sensitive. Because there are no pointers in AWK, all
arguments to functions are passed by value rather than by passing a pointer to
the actual variable. Thus, a function cannot modify the original variable
because it doesn't know the location of the variable.  It only has the value
contained in the variable.


ΓòÉΓòÉΓòÉ 7.2.7. Statements and Expressions ΓòÉΓòÉΓòÉ

The types of statements supported by the PEL compiler include declaration
statements, expression statements, iteration, and flow-control.  Statements are
terminated by the end of line character or (optionally) by a semicolon.  A
semicolon may also be used to represent a null statement. Expression statements
consist of primary expressions, which may be combined with other expressions by
operators.  Primary expressions include variables, constant strings and
numbers, and function calls.

Note: See the Variable declaration syntax section for a description of
declaration statements.


ΓòÉΓòÉΓòÉ 7.2.7.1. Multiple Line Statements ΓòÉΓòÉΓòÉ

To make source code more readable, statements are often made to extend across
two or more lines through the use of the backslash (\).  Lines ending with a
backslash are combined with the line that follows it to form a single logical
line.


ΓòÉΓòÉΓòÉ 7.2.7.2. Truth Values ΓòÉΓòÉΓòÉ

All expressions may be considered to have a TRUE or FALSE value.  This allows
them to be used in control structures to determine the flow of the program.
Expressions that have a numeric value are considered to be TRUE if the value is
other than zero.  They are treated as FALSE if the value is zero. Similarly,
empty strings have a FALSE value, while all other strings are considered to be
TRUE.  See Flow control and iteration to see how expressions are used in
control structures.


ΓòÉΓòÉΓòÉ 7.2.7.3. Expressions Containing Mixed Types ΓòÉΓòÉΓòÉ

Unlike many programming languages, PEL will not give you error messages if you
mix data types in expressions or statements.  PEL considers every number to
have a string equivalent and every string to have a corresponding numeric
value, even if that value is zero.

The string corresponding to the number 23 is "23". The value corresponding to
the string "nine" is 0. The string "nine" is a word rather than a string
representation of a number.  Any string that is not a representation of a
number has a corresponding value of 0.  However, the value given to the string
"3 Stooges" is 3.  The string needs to contain a string representation of a
number and must begin with a number in order to have a value greater than 0.
You can therefore use strings where PEL expects numbers, and numbers where
strings are expected.  If PEL does not see the data type it expects, it
automatically converts the data type of the data that it found.

The way to control the data type PEL assigns to data is to control what PEL
expects.  When you use arithmetic operators, PEL expects numbers.  When you
perform string operations such as concatenation, PEL expects strings.
Similarly, PEL may expect you to use a number as an argument to a function and
find that you have used a string.  Again, PEL performs an automatic data type
conversion.

In normal use, the operators and context you use indicate the data type you are
using.  However, if you need to force a desired type, simply combine the data
type you are using with the desired data type. Specifically, adding 0 to a
string converts it to a number.  Concatenating "" (an empty string) with a
number converts it to a string.  These operations change the type without
changing the perceived value.

Note: The PEL compiler accepts some special data types that are not native to
AWK.  These data types are used to denote special integers used to identify
specific buffers, keymaps, windows, and so forth. The data types may not be
converted or combined with any other type.  They may, however, be compared to
NULL to see if they are valid.  You can determine the type of any variable
using the typeof() function.


ΓòÉΓòÉΓòÉ 7.2.8. Operators ΓòÉΓòÉΓòÉ

The operators available in PEL are divided into the following categories:

Arithmetic operators

Assignment operators

Comparison operators

Logical operators

String operators

Array operators

Conditional operators


ΓòÉΓòÉΓòÉ 7.2.8.1. Arithmetic Operators ΓòÉΓòÉΓòÉ

All arithmetic in PEL is of the 32-bit integer variety.  Binary operators,
i.e., operators that act on two expressions, use the following format:

<expression> <operator> <expression>

Binary Operators

Operator  Definition

+         addition

-         subtraction

*         multiplication

/         division

%         modulo

PEL also supports unary operators, i.e., operators that act on a single
expression.  Unary operators use the following format:

<operator><expression>

Unary Operators

Operator  Definition

+         plus

-         minus

++        increment variable by 1

--        decrement variable by 1

Of the unary operators, the last two may be placed before or after the
expression.  However, the expression to which they are applied may only be a
variable.  If the expression to which they are applied is part of a larger
expression, the position of these operators is significant.  When the operator
precedes the variable, the variable is incremented or decremented before the
larger expression is evaluated.  When the operator follows the variable, the
variable is incremented or decremented only after the larger expression is
evaluated.


ΓòÉΓòÉΓòÉ 7.2.8.2. Assignment Operators ΓòÉΓòÉΓòÉ

The basic assignment operator is the equal sign.  It is used to set a variable
to the value of an expression using the following format:

<variable> = <expression>

Additional assignment operators are available that serve as shorthand for more
complex expressions. These assignment operators combine the equal sign with
other operators to produce the following syntax:

<variable> <oper>= <expression>

The form above is shorthand for the syntax below:

<variable> = <variable> <oper> <expression>

Assignment Operators

Operator  Definition

+=        add and assign

-=        subtract and assign

*         multiply and assign

/=        divide and assign

%=        modulo and assign


ΓòÉΓòÉΓòÉ 7.2.8.3. Comparison Operators ΓòÉΓòÉΓòÉ

Comparisons are evaluated to either TRUE or FALSE. Numbers may be compared to
other numbers and strings may be compared to other strings.  When comparing
numbers with strings, PEL determines which type of value is expected from the
context.  To be certain of the type of comparison you are performing, either
the number or the string may be converted so the expressions compared are the
same type.  Strings are compared using a case-sensitive lexical comparison.

Comparison Operators

Operator  Definition

==        equality

|=        inequality

<         less than

>         greater than

<=        less than or equal

>=        greater than or equal

~         string matches regular expression

!~        string does not match regular expression


ΓòÉΓòÉΓòÉ 7.2.8.4. Logical Operators ΓòÉΓòÉΓòÉ

Logical operators cause the expressions in which they are used to be evaluated
to TRUE or FALSE conditions.

Logical Operators

Operator  Definition

||        logical OR ( <expr> || <expr> )

&&        logical AND ( <expr> && <expr> )

!         logical complement (!<expr> )

PEL evaluates expressions containing logical AND or logical OR operators using
"short circuit" evaluation.  If the first sub-expression is sufficient to
determine the TRUE or FALSE condition, the remainder of the expression is not
evaluated.


ΓòÉΓòÉΓòÉ 7.2.8.5. String Operators ΓòÉΓòÉΓòÉ

 This category includes two types of string operations that differ from the
types of operations described above.  These are string concatenation and
regular expression matching.

String Concatenation

String concatenation differs from the preceding categories in that it requires
no operator.  An expression containing two or more strings, separated by one or
more spaces or tabs, are automatically concatenated into a single string.  The
strings can be variables or constants or a mixture of both. Some examples of
string concatenation are shown below:

ThisStr = "stuff&" "nonsense"
ThatStr = "more " ThisStr
message("Error:  " ThatStr)
myStr = "Don't forget to" taskStr " today."

Regular Expression Matching

Regular expression matching uses the operators ~ (match) and !~ (not match).
These operators result in True/False values only.  They are used in the
following form:

<regex> <oper> <stringex>

where regex is a regular expression, oper is either ~ or !~ and stringex is any
string variable, string constant or combination.  The regular expressions used
in conjunction with these operators follow the rules outlined in the section
titled Regular expressions  When the ~ operator is used, if the regular
expression matches a portion of the string expression the larger expression
evaluates to TRUE.  Otherwise, the expression evaluates to FALSE.  When the !~
operator is used, the opposite values are returned.

Example of Both Operators

One of the simplest examples and the best uses of these two operators involves
testing whether a character occurs in a given string.  Using select(), replace
the cindex() function with the !~ operator:

do
{

   ch = toupper( chr(getchar()) )

} while (ch !~ keyStr)

This example repeatedly reads the keyboard until the character received matches
one of those in the variable keyStr.  Using this form makes the code simpler,
more readable, and faster.


ΓòÉΓòÉΓòÉ 7.2.8.6. Array Operators ΓòÉΓòÉΓòÉ

The array operator in also results in a True/False evaluation.  It uses the
following format:

<expr> in <arrayvar>

where expr is any string or numeric expression and arrayvar is any array.  The
expression evaluates to TRUE if one of the indices of the array is the same
value as expr.  If expr is not a member of the array, the larger expression
evaluates to FALSE.


ΓòÉΓòÉΓòÉ 7.2.8.7. Conditional Operators ΓòÉΓòÉΓòÉ

The conditional, or ternary operator selects between expressions in a
statement. It is primarily a shorthand form of the if..else flow control (see
the section titled "Flow Control and Iteration" below). Yet because it is part
of an expression rather than being part of a statement, it can be used to
select between expressions in a statement. The syntax for the conditional
operator is:

<expression> ? <expression a> : <expression b>

If expression evaluates to TRUE, expression a is used.  Otherwise, expression b
is used.  For example:

var = (var == 0) ? 10 : (var - 2)


ΓòÉΓòÉΓòÉ 7.2.9. Flow Control and Iteration ΓòÉΓòÉΓòÉ

As stated earlier, expressions can be evaluated to a TRUE or FALSE condition.
This enables you to take actions based upon this condition.  The flow control
features in a programming language allow you to do this.  TRUE and FALSE
conditions may also be used to control iteration.


ΓòÉΓòÉΓòÉ 7.2.9.1. Flow Control ΓòÉΓòÉΓòÉ

PEL's flow control constructs include if and if..else.

The if construct is formed in this manner:

if (<expression>) <statement> [;]

Statement is only executed if expression evaluates to TRUE.  The construct can
optionally be terminated with a semicolon.  The if..else construct is formed in
a similar manner:

if (<expression>) <statement1> [;]
else <statement2> [;]

If expression evaluates to TRUE, statement1 is executed.  Otherwise, statement2
is executed. Either of these statements can optionally be followed by a
semicolon.

Both if and if..else constructs may be nested.


ΓòÉΓòÉΓòÉ 7.2.9.2. Iteration ΓòÉΓòÉΓòÉ

The three types of iteration or looping supported by PEL are for, while, and
do..while.  There are two formats available for the for loop.  The first format
is as follows:

for (<expr1>;<expr2>;<expr3>) {

   <statement1> [;]
   [<statement2> [;]]
   .
   .

}

The first expression in the for loop is used for initialization, the second
provides a test to determine the end of the loop, and the third modifies the
loop variable.

The second format of the for loop is as follows:   for (<variable> in <array>)
{

<statement1> [;]

   [<statement2> [;]]
   .
   .

}

The statements contained between the curly braces are repeated, once for each
member of the <array>. The <variable> expression is named by the user and
requires no other declaration.  During each loop, <variable> is set to the
value of the current subscript of the array.  This value may be used in the
statements by referencing <variable>. The while loop tests an expression at the
top of the loop to determine if another loop should be executed, as shown in
the following example:

while (<expr>) {

   <statement1> [;]
   [<statement2> [;]]
   .
   .

}

The do...while loop tests an expression at the bottom of the loop to determine
when to stop looping, as shown in the following example:

do {

   <statement1> [;]
   [<statement2> [;]]
   .
   .

} while (<expr>) [;]


ΓòÉΓòÉΓòÉ 7.3. Writing a PEL Function ΓòÉΓòÉΓòÉ

Now that you can read PEL source code, you are ready to try writing a function.
After that you will be ready to write extension programs on your own.


ΓòÉΓòÉΓòÉ 7.3.1. Scenario and Solution ΓòÉΓòÉΓòÉ

Suppose you need to re-read the file you are editing from the disk.  This is
sometimes necessary if you have run an external command from within the editor
that has resulted in changes to the file rather than to the buffer.  This could
occur as the result of something as simple as storing a copy of the file in
PVCS or other version control system.  If the editor does not know that the
file has received some external changes, its assumptions about the file on disk
will be wrong.  To avoid the confusion that these false assumptions might
cause, the file should be re-read from the disk.

You can perform this task with your normal keyboard commands without any
difficulty.  But because you will do this regularly, you want to write a
function to automate the procedure.

Solution

To write this function,

 1. Create a source code file with :.  Since this file contains the reload()
    function, a fitting name for the file would be RELOAD.PEL.  The extension
    .PEL is the file naming convention for : extension language source code
    files.

 2. Start a PREDITOR/2 session and retrieve RELOAD.PEL.  To do this, first
    change to the PEL subdirectory, then type C RELOAD.PEL and press [Enter].

 3. Insert a comment in the file describing the reload() function, then add an
    empty function:

   #   reload - reloads the current file from disk.
   #


   function reload()
   {


   }

The comment identifies the reload() function as one that reloads the current
file from disk.  The function keyword defines this function to PEL.  At this
point, there are no declarations or other statements in the body of the
function (between the curly braces), but these will be added.

 4. Determine what steps are necessary to complete the job reload() must
    perform.  For this example, the function should get rid of the buffer that
    does not match the file on disk, and then open a new buffer.  You can enter
    these steps first as comments or pseudo-code, and then build on that
    foundation:

   function reload()
   {

      # Save away the name of the current file.
      # We can delete the current buffer, even if
      # it's the only buffer. Delete it.
      # Use saved name to create new buffer for
      # editing. Causes file to be re-read.

   }

Here we see that we need a string variable in which to store the file name.

 5. Place a local variable declaration for a string to contain the file name
    within the curly braces. Then locate the internal variables and library
    functions that allow you to perform the steps outlined in the comments.

    When you are finished, your PEL code should look  like this:

   #   reload - reloads the current file from disk.
   #
   function reload()
   {

      local filenameStr


      # Save away the name of the current file.
      filenameStr = buffer_filename


      # We can delete the current buffer, even if
      # it's the only buffer. Delete it.


      delete_buffer(current_buffer)


      # Use saved name to create new buffer for
      # editing. Causes file to be re-read.
      return edit_file(filenameStr)

     }

The internal : variable buffer_filename contains the name of the file that is
being edited. After deleting the buffer, you lose access to this name.  Since
you need the name when creating the new buffer, you need to store it before
getting rid of the current buffer.

Another internal variable, current_buffer, contains the identification number
of the active edit buffer. You can use this variable to indicate to the
delete_buffer() function which buffer is no longer desired.

Finally, use the filename previously stored in the local variable filenameStr
to open a new buffer, and read the file into it.  The edit_file() function does
this for you in one step.  When this function has completed, you can continue
editing the file. The return keyword preceding the call to edit file() causes
the value obtained from edit_file() to be returned to any program that calls
reload(). Normally, this function is assigned to a keystroke, and the value
returned from reload() would be irrelevant.  If, however, you want to call this
function from another function, the return value might be useful.

 6. Compile the file.


ΓòÉΓòÉΓòÉ 7.4. PEL Compiler ΓòÉΓòÉΓòÉ

The PEL compiler supplied with PREDITOR/2 is a special version of Thompson
Automation, Incorporated's AWK compiler.  The AWK compiler creates stand-alone
executables from AWK source code while the PEL compiler produces programs that
PREDITOR/2 can execute.

PEL is an incremental compiler.  This means that when you recompile your CPE.AE
function library, only the changed modules are recompiled.  This ensures that
you spend a minimal amount of time waiting for the function library to
recompile after making minor changes.  For example, if out of the forty library
source files specified, only LOCAL.PEL has been modified, PEL recompiles only
LOCAL.PEL and incorporates it into the existing library. The PEL compiler also
offers some useful Lint-like features.  These include telling you when a
variable has been declared but not used, used but never declared, or
initialized more than once.


ΓòÉΓòÉΓòÉ 7.4.1. Parameter Description and Format ΓòÉΓòÉΓòÉ

The PEL compiler accepts two types of parameters: options (flags) and a file
list.  These parameters are described below.  They use the following format:

PEL  [<options>]  <file_list>

where options indicates the desired option and any associated arguments.  (See
"Options," below.)  The file_list parameter indicates a list of files to be
compiled.  (See the "List File" section below.)


ΓòÉΓòÉΓòÉ 7.4.1.1. Parameter Options ΓòÉΓòÉΓòÉ

 The available options and their descriptions are listed below:

add files (-a): This option enables you to add the specified files to the
function library without removing functions already in the library.  If this
option is not specified, the function library will contain only the functions
found in the files listed for processing.

internal compile (-i): This option enables you to recompile your library
executable without exiting PREDITOR/2.  If you recompile PREDITOR/2's library
executable from within the editor and do not use this option, the editor will
abort operation soon after the compile has been completed.

compress file (-compress): Compresses the file.  Note: Do not use this option
if you plan to use the PEL debugger.

output file (-o<output_filename>): This option enables you to specify the name
that the PEL compiler will give to the file it produces.  The <output_filename>
argument is the name given to the file, which can optionally include a
directory name. When this flag is not specified, the compiler produces a file
named CPE.AE.  Since PREDITOR/2 looks for a file named CPE.AE when it is
invoked, the default name is usually desirable.  If you produce a file with
another name, you will have to specify that file when invoking CPE by using the
- a<new_ae_file> option.

strict declarations (-s): This option tells PEL to issue warnings if a variable
is used without being declared.  PEL does not require that variables be
declared before they are used.  However, if you are following a policy of
declaring variables, this option will help you spot typographical errors and
other unintended uses of the variable.

verbose output (-v): This option causes PEL to display detailed information
about what file it is compiling or binding at each step of the compile.

list file (@<flist_filename>): This option may be used instead of, or in
addition to the file_list parameter.  The <flist_filename> argument indicates a
file containing a list of filenames to compile.  This input file may contain
filenames and any options you wish PEL to use. Files to be processed are placed
in the file, one on each line.  If a filename in the list does not have an
extension and cannot be located on disk, the extension . PEL is appended to the
name.  PREDITOR/2 then attempts to locate the file again.  The file specified
by this option typically contains a list of the files used to create the
PREDITOR/2 library. The list file option is used to rebuild the CPE.AE library
file.  All library component files must be specified in a single command when
rebuilding this file.  This typically results in a command line longer than the
operation system can handle.  The file list option provides a method of
overcoming this limitation.  WPEL.RSP is an example of this type of file.  It
is used to compile the files that make up the CPE.AE file as it was shipped on
your distribution disks.

File List:  The file list parameter is optional only if you have specified the
@<flist_filename> option.  Otherwise, it is required.  The filenames supplied
are separated by spaces and may contain standard OS/2 wildcard characters.


ΓòÉΓòÉΓòÉ 7.4.2. Environment Variables ΓòÉΓòÉΓòÉ

The PEL compiler creates a temporary file during compilation.  When determining
where to place this temporary file, PEL searches the environment for a variable
named TMP.  When PEL finds that the value associated with this variable
describes a valid directory, that directory is used for the temporary file.  If
the variable is not found or does not describe a valid directory, the current
directory is used for temporary storage.

It is important that the temporary area contains enough storage for the
temporary file, or the PEL compiler will be unable to complete the compilation.
It is not uncommon for PEL to use 512K of temporary space when performing a
complete rebuild of the function library.  If the TMP environment variable
points to a small RAM disk, PEL may discontinue processing and display an error
message when it runs out of temporary storage.


ΓòÉΓòÉΓòÉ 7.4.3. Compiling an Edited File ΓòÉΓòÉΓòÉ

When modify a file, you must compile the file before the editor will recognize
your changes.  To do this, you need to rebuild the library file CPE.AE.  This
file contains all of the compiled functions the editor uses.  The .AE extension
stands for AWK executable.  It is not an executable file in the same sense that
an .EXE file is executable. PREDITOR/2 reads this file when you start up the
editor.  The interpreter in the editor executes its contents.

The compiler used to generate the CPE.AE file is named WPEL.EXE.  This section
takes a direct approach to compiling extension language functions. (See the PEL
Compiler section for further information on the compiler.)  Here it is presumed
that you are working from an OS/2 prompt and that you are currently in the PEL
subdirectory of the PREDITOR/2 directory.

 1. To make a new CPE.AE file, compile all of the source code files listed in
    the WPEL.RSP response file.  The PEL compiler is an incremental compiler.
    This means you don't have to wait while unchanged files are recompiled,
    because only the files that have been changed or added to the list are
    compiled.

 2. If you have created a new function in a new file, such as RELOAD.PEL, add
    the name of that file to the beginning of the list in WPEL.RSP.  If you are
    just modifying your local_setup() function, you do not need to modify
    WPEL.RSP.

 3. After you have saved the WPEL.RSP file to disk and returned to the OS/2
    prompt, you are ready to re-make the AE file.

 4. Be sure you are in the PEL subdirectory of the PREDITOR/2 home directory
    before continuing.  Then issue the following command:

   WPEL  -s  -v  @WPEL.rsp

You may wish to redirect the output from this command into a file for
reference.  (We suggest the name PEL.ERR for capturing errors.)  If no errors
are reported, a new CPE.AE file is stored in the PEL directory.  You can try
out this new library file by running PREDITOR/2 from the PEL directory.  If it
doesn't work properly, you can rename or delete the new CPE.AE file after you
have established the cause of the problem.  PREDITOR/2 will then use the
original CPE.AE file in the parent directory as you edit the source files
before recompiling.  When you have established that the CPE.AE file in your PEL
directory is working as desired, you can copy it to your PREDITOR/2 home
directory.


ΓòÉΓòÉΓòÉ 7.5. PEL Debugger ΓòÉΓòÉΓòÉ

The PEL debugger is a tool to help you quickly and easily debug your PEL
functions.  When you use the debugger, you can watch your PEL executing and see
why problematic code doesn't work as you expect it to.  This debugger operates
much like a "C" debugger.

PEL Debugger Menus

Using the PEL Debugger

Helpful Hints for Debugging


ΓòÉΓòÉΓòÉ 7.5.1. PEL Debugger Menus ΓòÉΓòÉΓòÉ

 The available PEL debugger menus and their selections are described in the
following sections:

PEL Debugger Menus:File

PEL Debugger Menus:Breakpoints

PEL Debugger Menus:Run

PEL Debugger Menus:View

PEL Debugger Menus:File


ΓòÉΓòÉΓòÉ 7.5.1.1. PEL Debugger Menus:File ΓòÉΓòÉΓòÉ

Use this Option     To

Open                Open a file in the debugger.

Exit                Close the debugger.


ΓòÉΓòÉΓòÉ 7.5.1.2. PEL Debugger Menus:Breakpoints ΓòÉΓòÉΓòÉ

Use the function from the Breakpoints menu to set, clear, and view breakpoints.

Use this Option     To

List                Display a list of the current breakpoints.

Set/Clear           Set or clear a breakpoint.  You can also toggle a
                    breakpoint on and off by double-clicking the mouse in the
                    line number area of the current PEL file.

Clear all           Clear all breakpoints.  : You can also clear all
                    breakpoints from the breakpoint list dialog box.


ΓòÉΓòÉΓòÉ 7.5.1.3. PEL Debugger Menus:Run ΓòÉΓòÉΓòÉ

Use the Run menu options to execute PEL code.

Use this Option     To

Go                  Begin executing your PEL code. The code will continue to
                    execute until it reaches a breakpoint.

Step into           Cause the debugger to execute one line of PEL code,
                    stepping into any PEL function calls made in that line of
                    code.

Step over           Cause the debugger to execute one line of PEL code,
                    stepping over any PEL function calls made in that line of
                    code.


ΓòÉΓòÉΓòÉ 7.5.1.4. PEL Debugger Menus:View ΓòÉΓòÉΓòÉ

Use the selections from the View menu to display variable values.

Use this Option     To...

Call stack          Display a list of all functions that have been called.

Local variables     Display a list of any parameters passed into the function
                    you are debugging, along with any variables local to that
                    function. The type and value of each variable are also
                    displayed.

Variable            Query the type and value of the variable (local or global
                    PEL) under the cursor.  You can also double-click on the
                    variable you want to query, or enter the name of the
                    variable.


ΓòÉΓòÉΓòÉ 7.5.1.5. PEL Debugger Menus:Search ΓòÉΓòÉΓòÉ

Use the selections on the Search menu to locate specific strings of text.

Use this Option     To

Search              Locate a specific search string.

Search again        Locate a previously specified search string.


ΓòÉΓòÉΓòÉ 7.5.2. Using the PEL Debugger ΓòÉΓòÉΓòÉ

To debug PEL functions, you must first compile the .AE file without the
-compress option.  Make this change by editing the MAKE_AE.CMD file in your PEL
subdirectory.  Then rename the file CPE.AE to CPE.BAK and recompile the
function library by running MAKE_AE.CMD.

To run the PEL debugger,

 1. Select the Tools menu on the menu bar.

 2. Click on the PEL debugger menu item.  The PEL debugger is displayed.

 3. From the File menu, open the file you want to debug.

 4. Set breakpoints (by double-clicking at the beginning of a line) wherever
    necessary.  You can set breakpoints only on lines that contain actions:
    variable assingments, function calls, or variable queries.  If you set a
    breakpoint on an invalid line, the debugger will not recognize the
    breakpoint, and simply pass over it.

 5. Click on the Go button.

The main PREDITOR/2 window is brought to the foreground.  At this point, you
can continue using the editor normally until the PEL code in which you have set
breakpoints executes.

After a breakpoint is reached, the editor window is disabled and the debugger
window is displayed, showing the source code of the current breakpoint.  You
can then query the value of any variable, step through the PEL code, and
determine the source of errors.


ΓòÉΓòÉΓòÉ 7.5.3. Helpful Hints for Debugging ΓòÉΓòÉΓòÉ

The following are some helpful hints for working effectively with the PEL
debugger.

Startup

The debugger cannot debug PEL effectively until PREDITOR/2 is completely
started.  This is because you cannot start the debugger until PREDITOR/2 has
completed its initialization process.

If you need to debug PEL that is normally called during PREDITOR/2
initialization, first test and debug the PEL functions after startup.  Once
these functions are working, place them in the initialization of the editor.

Setting Breakpoints

The following guidelines will be helpful for you to remember when setting
breakpoints:

o A valid breakpoint is any line that contains either a variable query, a
  variable assignment, or a function call.

o You cannot set a breakpoint on the function name itself, or on the
  declaration of a local variable unless that declaration includes an
  assignment.

o For commands that continue across multiple lines, only the last line is a
  valid breakpoint.

The following is an example of setting a breakpoint:

global function my_function()
{
   local var1
   local var2 = "test" # variable assignment,valid breakpoint

   # just a demo comment
   if ( var2 )    # variable query, valid breakpoint
   {
      warning( "This is a %s", var2 ) # function call, valid breakpoint
   }
}

Events

It is possible to set breakpoints in mouse event handlers, but if, for example,
you break in an EVENT.MOUSE_LEFT_DOWN handler, you will not get the
EVENT.MOUSE_LEFT_UP event if you have a function attached to it.  This results
from the debugger preventing the PREDITOR/2 editor window from getting any
further input when you break.

Debugging other PEL event handlers may be difficult in similar circumstances.

Changing Source Code

If you change the source code as you are running the PEL debugger, the debugger
will not automatically recognize the changes.  You must close the file,
recompile the source code, and start the debugger again.  Until you do this,
the debugger will still be reading the original code.


ΓòÉΓòÉΓòÉ 8. Template Expansion ΓòÉΓòÉΓòÉ

Templates are handy programming aids.  The following categories provide
instructions for working with the templates:

Specifying a Template

Enabling/Disabling a Template

Expanding a Template

Adding/Changing a Template


ΓòÉΓòÉΓòÉ 8.1. Specifying a Template ΓòÉΓòÉΓòÉ

The editor recognizes the extension of your file name and opens its
corresponding template.  For example, if you are editing a file named TEST.C, a
C/C++ template is expanded when you enable template expansion.

The table below lists the extensions the editor recognizes for currently
supported templates.  You can add your own template by editing the ELECTRIC.PEL
file.  Be sure to also add the extensions applying to that template.

Language     Extensions

AWK          .PEL, .AWK

C, C++       .C, .H, .HPP, .CPP, .CXX, .HXX

Clipper50    .PRG, .CH, .PPO, .GEN, .COD, .GTL, .TLB, .TEM

Clipper '87  .PRG, .PRE, .GEN, .COD, .GTL, .TLB, .TEM

COBOL        .COB, .CBL

dBase        .PRG, .GEN, .COD, .GTL, .TLB,.TEM

Pascal       .PAS

REXX         .CMD


ΓòÉΓòÉΓòÉ 8.2. Enabling/Disabling a Template ΓòÉΓòÉΓòÉ

 By default, PREDITOR/2's templates are disabled. To use a temlate, you must
enable template expansion.

To enable template expansion,

 1. Select the Settings item on the Options menu.  The settings notebook will
    open.  Click on the Types tab and then the Template subtopic tab.

 2. Select the type of file for which you wish to enable template expansion(for
    example, "c").

 3. Choose the correct template from the template list(for the previous
    example, again, "c").

 4. Check/Uncheck the template expansion checkbox to enable/disable template
    expansion for that template and file type.

 5. Click on the notebook's OK button.  Your changes will be recognized
    immediately.


ΓòÉΓòÉΓòÉ 8.3. Expanding a Template ΓòÉΓòÉΓòÉ

 When template expansion is enabled, you can expand a template by entering the
appropriate key combination.  For key combinations and their corresponding
templates, refer to Appendix D: Language- specific Templates in the PREDITOR/2
User's Guide.

To expand a template,

 1. Position the cursor at the location in the buffer (file) where you want to
    expand the template.

 2. Enter the key combination (noting case- sensitivity, where applicable) and
    press the [space bar].  The template is immediately expanded into the file.

To move to the next field in an expanded template,

 1. Press [Ctrl][Enter].  The next field is highlighted and ready to be
    changed.


ΓòÉΓòÉΓòÉ 8.4. Adding/Changing a Template ΓòÉΓòÉΓòÉ

 The editor also supports templates you add or change.  All templates are
defined in the ELECTRIC.PEL file.  You can permanantly add your own templates
or change current templates by editing this file, saving your changes, and
recompiling the CPE.AE file.

You will use several important symbols when you add templates.  These symbols
are explained in the table below.

This Symbol       Means

@                 Place cursor here after the template has been inserted.

\n                Insert new line and auto-indent.

\r                Insert new line.

\t                Insert tab.

\b                Un-indent one level.

`...`             Enclosed content is a field character.

You can also add temporary templates that will work until you exit the editor.
Add temporary templates with the template_add() function.

To add temporary templates,

 1. Open the Command dialog from the Tools menu.

 2. Type template_add and click on the OK button, or press [Enter].  A dialog
    box prompts you to enter the Template characters.

 3. Type the key(s) you want your template to correspond to, and press [Enter].
    A dialog box now prompts you to enter the Template expansion.

 4. Enter the template you want to generate when you expand the keystroke you
    specified in Step 3, and press [Enter].

Your new template is added.


ΓòÉΓòÉΓòÉ 8.5. Using Fields ΓòÉΓòÉΓòÉ

Some templates have fields.  Fields are strings surrounded by grave accents
that can be used as markers indicating where you should enter fields relating
to your template.  For example: `statement-1`.

By default, the [Ctrl][Enter] key combination enables you to move to
consecutive fields.  When you use [Ctrl][Enter] to move to a field, that field
is highlighted.  Any character you type overwrites that field.


ΓòÉΓòÉΓòÉ 9. Menu Options ΓòÉΓòÉΓòÉ

All of the PREDITOR/2 features are arranged in the menus that are displayed on
the menu bar. The menu bar is located across the top of the PREDITOR/2 window,
just below the title bar.  Items in the editors pull-down menus perform one of
three types of actions:

o Starting a feature

o Opening a dialog box

o Opening another menu.
 The editor's menu bar gives you the following menus:

File menu           Lets you perform operations that affect files.  For example
                    opening, saving and printing files.

Edit menu           Lets you perform edit functions such as undo, cut, copy and
                    paste.

Search menu         Lets you perform single- or multiple-buffer search
                    functions like find, change and symbol matching.

Buffers menu        Lets you switch buffers or display a list of currently open
                    buffers.

Tools menu          Lets you execute an editor or system command, run the pel
                    debugger, create tags files and more.

Options menu        Lets you choose the settings for the editor like colors,
                    fonts and search options.

Window menu         Lets you create new windows, open and close existing
                    windows, and other window specific activities.

Help menu           Lets you access the PREDITOR/2 help library and product
                    information.

Shortcuts for Using Menus

Menu shortcuts enable you to work more quickly.  Two alternative options for
working with menus are:

To select a menu item, either:

o Type the underlined letter in the desired item (the mnemonic letter), or

o Type the key combination displayed next to the option. (This option does not
  work if the menu is pulled down.)

To close the menu, click elsewhere in the window.

The editor's toolbar affords quick access to certain file, edit, and buffer
functions.

The status bar has four areas that are of concern:

Message area        This is used by many functions to present all types of
                    information and is also where help text is displayed.

Indicator area      This is used to display some state information like
                    modified(MOD), read-only file(RO), num-lock key(NUM),
                    caps-lock key(CAPS), overtype mode(OVR), insert mode(INS),
                    and emulation mode(Brief, VI, CUA, Emacs, Native, ISPF).

Position area       This area is actually made up of two adjacent areas.  One
                    area can display the current line position and size of file
                    and the second area can display the current column
                    position.

Time/date area      This area can display the day of week, date and time (in 12
                    or 24 hour format)

For more information on these areas and how to manipulate them, see the See
also:.

See also:

o Toggle toolbar
o Toggle status bar


ΓòÉΓòÉΓòÉ 9.1. File menu ΓòÉΓòÉΓòÉ

From the File menu, you can perform a variety a functions on the current buffer
including opening, saving, and printing. Refer to the following sections for
more information on File menu options:

o New
o Open...
o Insert file
o Error file...
o Open file under cursor
o Save
o Save as...
o Save all
o Print
o Print Setup...
o Exit

See also:

o gui_open()
o edit_file_key()
o edit_unix_file_key()
o print()
o write_block_key()


ΓòÉΓòÉΓòÉ 9.1.1. New ΓòÉΓòÉΓòÉ

Select New to create a new buffer.  (Use Insert file to retrieve a file into
the current buffer.)

See also:

o create_buffer()
o edit_file()


ΓòÉΓòÉΓòÉ 9.1.2. Open ΓòÉΓòÉΓòÉ

To create a new buffer and insert a file into it, use the Open menu item. The
Open dialog box is displayed.

To open a file,

 1. Select Open.

 2. Enter the name of the file to be opened in the Open filename field.  If you
    do not know the file name, use the Type of file or Drive drop-down boxes,
    or the File or Directory list boxes to locate the desired file.

 3. Select the Open files in new window check box to open a window and retrieve
    the file into it.  If this box is cleared, any buffer opened is placed in
    the buffer list and opened into the first available open window.

 4. Select or clear the Read only check box as necessary.

 5. After you have made your selections, either click on OK to retrieve the
    file, or click on Cancel to exit from the dialog box without retrieving a
    file.

See also:

o edit_file()
o open_dialog()


ΓòÉΓòÉΓòÉ 9.1.3. Insert file ΓòÉΓòÉΓòÉ

Select Insert file to retrieve a file into an open buffer.  The Insert File
dialog box is displayed.

To insert a file,

 1. Enter the name of the file to be opened in the Open filename field.  If you
    do not know the file name, you can use the Type of file or Drive drop-down
    boxes, or the File or Directory list boxes to locate the desired file.

 2. After you have made your selections, either click on OK to retrieve the
    file (the retrieved file is placed at the cursor position) or click on
    Cancel to exit fromthis dialog box without inserting a file.

See also:

o read_file()
o transfer()


ΓòÉΓòÉΓòÉ 9.1.4. Error file ΓòÉΓòÉΓòÉ

When compiling in PREDITOR/2, compilation errors are displayed in a dialog box.
When compiling outside of the editor, errors may be directed to a file.  Using
the Error file option, PREDITOR/2 enables you to format this error file into a
dialog box analogous to the one displayed when compiling within the editor.
You can use this window to easily view the errors and quickly go to the
location in the source code where the error occurred.

To view your compilation errors,

 1. Compile your edited file and create an error file.

 2. Select Error file from the File menu.  The Display Error File dialog box is
    displayed.

 3. Enter the name of the file to be used, in the Error file name field.

 4. Indicate the compiler that was used in the drop-down box in the Compiler
    field.

 5. Press [Enter] or click on OK.  The editor displays a list box containing
    all of the compile errors.  If you do not want to view the list box right
    away, you can minimize the box by selecting the minimize icon in the upper
    right corner of the box.  Use the Dialog list function from the Tools menu
    to view the error list box, as well as other minimized list boxes.  Refer
    to Dialog list (Tools menu) for more information.

See also:

o Extensions


ΓòÉΓòÉΓòÉ 9.1.5. Open file under cursor ΓòÉΓòÉΓòÉ

This feature provides a link between a reference to a file and the actual file.

To open the file under the cursor,

 1. Position the cursor on a file name within an open file.

 2. Select Open file under cursor from the File menu.

The selected file is opened into a new buffer.

See also:

o read_file()
o symbol_under_cursor()


ΓòÉΓòÉΓòÉ 9.1.6. Save ΓòÉΓòÉΓòÉ

Use the Save option to save the current buffer to a file.  If the file has not
yet been given a name, the Save as dialog box is displayed.  See Save as for
more information.

See also:

o write_buffer()


ΓòÉΓòÉΓòÉ 9.1.7. Save as ΓòÉΓòÉΓòÉ

To save a highlighted block of text or to save an already-named file with a
different name, select Save as.  The Save As dialog box is displayed.

To save using the Save as option,

 1. Enter the name of the file to be saved, in the Save as filename field.

 2. specify the file type in the Save file as type drop-down box.

 3. Indicate the path of the specified file in the Drive drop-down box and the
    Directory list box.

 4. Click on OK to save the file, or click on Cancel to exit this dialog box
    without saving the file.

See also:

o write_buffer()


ΓòÉΓòÉΓòÉ 9.1.8. Save all ΓòÉΓòÉΓòÉ

Select Save all to save all modified buffers to your disk.

See also:

o write_all_buffers()


ΓòÉΓòÉΓòÉ 9.1.9. Print ΓòÉΓòÉΓòÉ

Select Print from the File menu to print the current buffer or portion of the
current buffer.  The Print dialog box is displayed.

 1. Use the radio buttons in the Print Range group box to indicate what
    portions of the buffer are to be printed.

    Below is a list of radio buttons and the information that is printed when
    you select from these buttons:

    All: The entire buffer.

    Selected: Only the highlighted portion of the buffer.

    Lines: A specific range of lines.  Use the From and To fields to indicate
    the first and last lines to print.

    Pages: A specific range of pages.  Use the From and To fields to indicate
    the first and last pages to print.

 2. In the Mode area, select how you want your file printed.  Below are the
    radio buttons you can select and a description of how each will print your
    file:

    Draft: Only the text, without headers, footers, sections, or other
    formatting codes.

    WYSIWYG: If WYSYWIG is selected then all the formatting options are used to
    print the buffer.  The printing options are configured by selecting the
    Options push button.

 3. Select the Select push button to choose which printer to use for printing.

 4. Select the Setup push button to display the printer specific setup dialog
    box. The Setup Dialog Box displayed is printer specific and supplied by the
    printer driver. This button is only avaiable when printing in WYSYWIG mode.

 5. Select the Options push button to configure options used in WYSYWIG mode.
    You can configure such things as headers/footers, fonts, and number of
    columns from the Options Dialog box.

See also:

o print_select_dialog()
o Print Setup
o Print Options
o print_buffer()
o print_dialog()


ΓòÉΓòÉΓòÉ 9.1.10. Print Options ΓòÉΓòÉΓòÉ

The Print Options dialog box allows you to configure how your buffer is printed
in WYSYWIG mode.

o Header and Footer To print a header or footer click on the appropriate check
  box in the Header or Footer group box. If you have selected the check box
  then you may configure the header or footer codes and select a font for
  printing the header or footer. Enter the appropriate codes in the entry
  fields. The table below describes available header and footer codes.

  Header and Footer Codes

    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
    ΓöéCode      ΓöéMeaning                       Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~_        ΓöéDrawLine                      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~L        ΓöéLeft                          Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~C        ΓöéCenter                        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~R        ΓöéRight                         Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~D        ΓöéDate                          Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~T        ΓöéTime                          Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~P        ΓöéPage No.                      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~f        ΓöéFile Name (Full Path Name)    Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~F        ΓöéFile Name (FileName Only)     Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~d"<fmt>" ΓöéFormatted Date                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~t"<fmt>" Γöé Formatted Time               Γöé
    Γöé          ΓöéWhere fmt = strftime argumentsΓöé
    Γöé          Γöé(See Page 333 of IBM CPI C RefΓöé
    Γöé          Γöé - Level 2)                   Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~p<num>   Γöé Page No.                     Γöé
    Γöé          ΓöéWhere num = length of page No.Γöé
    Γöé          Γöéthen the page No. is zero fillΓöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~b        ΓöéBold                          Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~i        ΓöéItalic                        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~u        ΓöéUnderline                     Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~s        ΓöéStrikethru                    Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~"<name>" Γöé Font Name                    Γöé
    Γöé          ΓöéWhere <name> = Font Name      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~<num>    Γöé Font Size                    Γöé
    Γöé          ΓöéWhere <num>  = Font Size      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~B        Γöé Bold                         Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~I        Γöé Italic                       Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~U        Γöé Underline                    Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~S        Γöé Strikethru                   Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~'<name>  Γöé Font Name                    Γöé
    Γöé          ΓöéWhere <name> = Font Name      Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé~#<num>   Γöé Font Size                    Γöé
    Γöé          ΓöéWhere <num>  = Font Size      Γöé
    Γöé          Γöé(Right, Left & Center)        Γöé
    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

o Long lines This option allows you to configure how lines longer than the
  width of the printed output are handled.

   - Truncate - selecting this option will not print lines that extend beyond
     the width of the printed output.

   - Split - selecting this option will cause long lines to be drawn as two or
     more lines. You can also specify how the long lines are split:

      o Word Wrap - will split long lines on word boundries.

      o Indent - will indent the second and subsequent lines to the right of
        the first line.

      o Program Indent - will handle long lines containing parenthesis as
        special cases. If a line is split and it contains an open parenthesis
        then the second and subsequent lines are indented to the right of the
        parenthesis until an ending parenthesis is found.  This is useful for
        printing program listings.

o Columns Enter the number of columns you want printed on one page.  A
  separator bar is drawn between the columns.

o Text Font Allows changing the font for printing the buffer text.

See also:

o Print
o Print Setup
o Print Fonts


ΓòÉΓòÉΓòÉ 9.1.10.1. Print Fonts ΓòÉΓòÉΓòÉ

The Print Font Dialog, Header Font Dialog, and Footer Font Dialog windows are
used to change the font used when printing.

The available fonts will be displayed, and any font selected by clicking on it
will immediately appear in the Sample display.

See also:

o Print


ΓòÉΓòÉΓòÉ 9.1.11. Print Setup ΓòÉΓòÉΓòÉ

The Printer setup option enables you to select a printer and specify its
parameters.

To specify your printer setup,

 1. Click on the appropriate printer named in the list box.

 2. Click on OK to exit this dialog box and print your file or click on Cancel
    to exit this dialog box without making any selections.

To specify printer parameters,

 1. Click on Job properties to specify parameters for this printer.  The
    Printer Properties dialog box is displayed.Use this dialog box to specify
    the properties of the destination printer.

 2. Select the Device defaults push button if you would like additional
    information on default device drivers.

    Select from the following buttons for additional information:

    Fonts: See a list of additional fonts.

    Forms: See a list of predefined forms.

 3. Click on OK, or click on Cancel to exit this dialog box.

See also:

o Print
o print_select_dialog()
o print_buffer()
o print_dialog()


ΓòÉΓòÉΓòÉ 9.1.12. Exit ΓòÉΓòÉΓòÉ

To exit PREDITOR/2, select Exit. Exit ends your editing session.  If you have
modified buffers you are prompted to save them.  The state and settings of your
session are stored in the 'CPE.CFG' if not otherwise specified in the Settings
Notebook.  The buffer list is also saved in in the config file, and each buffer
in the list will be opened when you start the editor next.

See also:

o done()
o quit()


ΓòÉΓòÉΓòÉ 9.2. Edit menu ΓòÉΓòÉΓòÉ

Use Edit in the menu bar to access editing and formatting options. of the
Editor.  You can select from the following choices:

o Undo
o Redo
o Cut
o Copy
o Append
o Paste
o Delete
o Upper
o Lower
o Indent
o Outdent


ΓòÉΓòÉΓòÉ 9.2.1. Undo ΓòÉΓòÉΓòÉ

Undo removes the last action in the window.  This includes cursor movements,
searches and character entry.  The undo list is specific to, and unlimited for
each buffer.  The undo list is cleared after each save.

See also:

o undo()
o undo_index()


ΓòÉΓòÉΓòÉ 9.2.2. Redo ΓòÉΓòÉΓòÉ

Redo replaces the last undone action.  You may redo all of the actions you have
undone.  There is no limit to the number of times you can undo or redo an
action taking place after your last save.

See also:

o redo()
o redo_index()


ΓòÉΓòÉΓòÉ 9.2.3. Cut ΓòÉΓòÉΓòÉ

Cut removes the highlighted section of the buffer from the buffer and places it
in the scrap buffer.  The block may be retrieved from scrap with the paste
command.

See also:

o delete_to_scrap()
o delete_chars()
o paste()


ΓòÉΓòÉΓòÉ 9.2.4. Copy ΓòÉΓòÉΓòÉ

This function copies the highlighted selection from the current buffer to the
scrap buffer.  The block may be retrieved later from the scrap buffer with the
paste command.

See also:

o copy_to_scrap()


ΓòÉΓòÉΓòÉ 9.2.5. Append ΓòÉΓòÉΓòÉ

Select Append to append, or copy, information to the scrap buffer without
destroying information previously stored there.


ΓòÉΓòÉΓòÉ 9.2.6. Paste ΓòÉΓòÉΓòÉ

Paste retrieves the last block moved to scrap and places it in the buffer at
the current cursor position.

See also:

o cut()
o insert_scrap()
o outdent_tabs()
o paste()


ΓòÉΓòÉΓòÉ 9.2.7. Delete ΓòÉΓòÉΓòÉ

Delete removes the highlighted section from the buffer.  It is not placed in
the scrap buffer, and can only be retrieved with the undo command.

See also:

o delete_to_scrap()
o delete_chars()


ΓòÉΓòÉΓòÉ 9.2.8. Upper ΓòÉΓòÉΓòÉ

Upper makes all of the characters in the highlighted section uppercase.

See also:

o upper()


ΓòÉΓòÉΓòÉ 9.2.9. Lower ΓòÉΓòÉΓòÉ

Lower makes all of the characters in the highlighted section lowercase.

See also:

o lower()


ΓòÉΓòÉΓòÉ 9.2.10. Indent ΓòÉΓòÉΓòÉ

Indent moves each line of the highlighted text to the right by one tab stop.

Hint: To indent/outdent multiple lines at one time, highlight the desired lines
before selecting Indent or Outdent.

See also:

o indent_tabs()


ΓòÉΓòÉΓòÉ 9.2.11. Outdent ΓòÉΓòÉΓòÉ

Outdent moves each line of the highlighted text to the left by one tab stop. If
one or more lines can not be moved further to the left, no action is taken.

Hint: To indent/outdent multiple lines at one time, highlight the desired lines
before selecting Indent/Outdent.

See also:

o outdent_tabs()


ΓòÉΓòÉΓòÉ 9.3. Search menu ΓòÉΓòÉΓòÉ

The Search menu contains options that enable you to perform several kinds of
searches, based on a variety of search criteria. When a search is invoked, the
default search settings presented in the dialog box represent the current
default settings.  Changing any of these settings causes the default settings
to change accordingly.  From the Search menu, you can select from the following
options:

o Find string...
o Find next
o Incremental find
o Change..
o Find matching
o Mark matching
o Mark next matching
o Find routines
o Locate line number...
o Bookmark list

See also:

o goto_matching()
o mark_matching()
o mark_matching_next()
o wgrep()
o routines()
o goto_line_key()


ΓòÉΓòÉΓòÉ 9.3.1. Find string ΓòÉΓòÉΓòÉ

To find a string,

 1. Select Find string.  The Find String dialog box is displayed.

 2. Enter the search string in the Search value field.

 3. Indicate where you would like PREDITOR/2 to search for the specified
    string, in the Scope group box:

    Then select one of the following radio buttons:

    Selected block: Search only the selected block of text.  This button is
    only available if you highlighted a block of text before you invoked the
    search.

    Current buffer: Search only the current buffer.

    All buffers: Search all open buffers.

    File(s): Specify files to search.  With this option selected, the Files to
    search field is enabled, where you can add the path and name(s) of the
    file(s) to search. Only the Change all button is available when you use
    this option.

    Recursive: Search the specified directory and all of its subdirectories.

 4. Specify if the search is to move forward or backward from the cursor
    position, in the Direction group box.  To do this, click on the appropriate
    radio button.

 5. Select the Match case check box if you want to perform a case-sensitive
    search.  Clear this box if you want to locate all matches of the search
    string regardless of case.

 6. Select or clear the Regular expressions check box.

 7. For additional search functionality, click on Options.  The Find dialog box
    expands to reveal additional check boxes.  The default values for these
    functions are shown.  You can select or clear the following check boxes as
    necessary:

    Highlight search results: Have the located search string shown as
    highlighted text.  Clear this check box to have the cursor move to the
    first character of the located text.  Click on the title bar to bring the
    located text into view.

    Center search results: Place the line containing the located search string
    in the center of the window.  Clear this check box to cause the located
    search string to remain in its original position.

    Find maximal match: Search for the longest string matching the search value
    criteria.  Clear this box to search for the first occurrence of the
    beginning string and the first occurrence of the ending string.

    Search wraps around: Wrap the search around the end of the buffer and
    continue searching until it comes back to the starting point if the
    specified search string is not found before the search reaches the end of
    the buffer.  Clear this box to stop the search when it reaches the end of
    the buffer without wrapping.

    Match whole word: Find only those occurrences of the search string
    (delimited by a valid delimiter) to be considered a match. Clear this check
    box to have no constraints put upon the search.

    Caution:  The Regular expressions check box must be selected if you use
    regular expressions in your search string.  For more information, see
    Regular expressions

    Note:  Word delimiters can be configured using the Settings notebook.  See
    the {*"Colors" section in Chapter 2 - Customizing*} for further
    information.

 8. Choose from the following options as you begin the search:

    Find: Search for the next occurrence of the search string.

    First: Locate the first occurrence of the search string, beginning at the
    top of the file.

    Last: Locate the first occurrence of the search string, beginning at the
    bottom of the file.

    Find All Search Button: Locate all occurrences of the search string and
    display them in a list box.

Hint:  Use the pop-up menu for a quick, context-sensitive search.  Within the
buffer you are searching, simply move the cursor to the word you are searching
for, press and release the right mouse button, and select the Find string menu
item from the pop-up menu that appears.

Search    value
          Enter the character string that you would like to scan for in the
          buffer.
          Scope
          Select the appropriate scope.  All Buffers searches all open buffers
          and File(s) allows file searching.
          Direction
          Select the direction to proceed scanning the buffer for the Search
          value relative to the current position. Options

See also:

o grep()
o Options
o search()
o wgrep()
o wsearch()


ΓòÉΓòÉΓòÉ 9.3.2. Search Options ΓòÉΓòÉΓòÉ

The search options may be set on the search settings page of the notebook or on
the Options panel of the Find and Change dialog.  When checked, the following
settings have the described effects.

o Match case - Invokes a case sensitive search.

o Regular expr. - Allows entering Regular expressions in the search value
  field.

o Find all - Finds all strings in the buffer matching the search value.

o Highlight search result - Highlight the strings matching the search value.

o Center search results - Centers the matched string in the window.

o Find maximal match - Finds the longest string matching the search value
  criteria.

o Search wraps around - Starts searching from the beginning of the buffer if no
  match is found before reaching the end of the buffer.

o Match whole word - Only finds strings matching the search value in length.


ΓòÉΓòÉΓòÉ 9.3.3. Find All Search Button ΓòÉΓòÉΓòÉ

When you select the Find All button, a dialog box is displayed if more than one
match if found.  All occurrences of the search string are listed in this list
box.

The editor provides a variety of methods for you to use this information, which
you can access by simply clicking on one of the buttons located across the
bottom of the list box:

Move the cursor in the file to a listed occurrence
          Highlight the occurrence (or use Next and Prev to move the cursor)
          and click on Goto, or double-click on an item in the list.

Move the cursor down the list of occurrences.
          Click on Next.  As you move through the list, the highlight bar moves
          through the file, stopping on the line containing the selected
          occurrence. Click on Goto to position the cursor on that line of the
          file.

Move the cursor up through the list of occurrences
          Click on Prev.  As you move through this list, the highlight bar
          moves through the vile, stopping on the line containing the selected
          occurrence. Click on Goto to position the cursor on that line of the
          file.

Discontinue the Find All process
          If there are numerous occurrences to be located, this process can be
          time-consuming.  In this situation, you can click on Stop to end the
          processing.

Close this dialog box
          Click on Close.

Minimize this dialog box for viewing at a later time
          Click on the minimize icon in the upper right corner of the dialog
          box. The minimized box can be viewed by selecting the Dialog list
          function.  See Dialog list for more information.


ΓòÉΓòÉΓòÉ 9.3.4. Find next ΓòÉΓòÉΓòÉ

Select Find next to locate the next occurrence of the previously specified
search string.  For information on changing the search string or any search
parameters, see Find string from the Search menu.

See also:

o search_again()
o wsearch_again()


ΓòÉΓòÉΓòÉ 9.3.5. Incremental find ΓòÉΓòÉΓòÉ

Select Incremental find to locate the first occurrence of a search string.  You
can add characters to the string or delete them.  Each time the search string
changes, the cursor moves to the first occurrence of the current string.

When you select Incremental find, the message Incremental find:* is displayed
in the status bar. (If you have toggled the status bar off, a message box is
displayed in which you can enter the string.).  At the cursor (*), enter the
search string.  The cursor moves to the first occurrence of the string. You can
add characters to the string or delete characters.  Any time the string
changes, the cursor moves to the first occurrence of the current string.

See also:

o search_i()


ΓòÉΓòÉΓòÉ 9.3.6. Change ΓòÉΓòÉΓòÉ

Use the Change option to locate a specified search string and replace it with
another.

To change a string,

 1. Select Change.  The Change String dialog box is displayed.

 2. Enter the string to be found, in the Search value field.

 3. Enter the replacement string in the Change to value field.

 4. Indicate where you would like the editor to search for the specified
    string, in the Scope area:

    Selected block: Search and change only the selected block of text.  This
    option is enabled only if you highlighted a block of text before invoking
    the search.

    Current buffer: Search and change only the current buffer.

    All buffers: Search all open buffers.

    File(s): Specify files to search.  With this option selected, the Files to
    search field is enabled, where you can add the path and name(s) of the
    file(s) to search. Only the Change all button is available when you use
    this option.

    Recursive: Search the specified directory and all of its subdirectories.

 5. In the Direction group box, use the radio buttons to specify if the search
    is to proceed forward or backward from the cursor position.

 6. Select the Match case check box to make the search case-sensitive.  Clear
    this box to locate all matches of the search string regardless of case.

 7. Select or clear the Regular expressions check box.

 8. Click on Options for additional functionality.  The Change dialog box
    displays additional check boxes.  The default values for these functions
    are shown.  You can select or clear the check boxes as necessary:

    Highlight search results: Have the located search string shown as
    highlighted text.  Clear this check box to have the cursor move to the
    first character of the located text.  Click on the title bar to bring the
    located text into view.

    Center search results: Place the line containing the located search string
    in the center of the window.  Clear this check box to cause the located
    search string to remain in its original position.

    Find maximal match: Search for the longest string matching the search value
    criteria.  Clear this box to search for the first occurrence of the
    beginning string and the first occurrence of the ending string.

    Search wraps around: Wrap the search around the end of the buffer and
    continue searching until it comes back to the starting point if the
    specified search string is not found before the search reaches the end of
    the buffer.  Clear this box to stop the search when it reaches the end of
    the buffer without wrapping.

    Match whole word: Find only those occurrences of the search string
    (delimited by a valid delimiter) to be considered a match.  Clear this
    check box to have no constraints put upon the search.

    Note:  The Regular expressions check box MUST be selected if you are using
    regular expressions in your search string.

 9. You can choose from the following options as you begin the search:

    Find: Search for the next occurrence of the search string.

    First: Locate the first occurrence of the search string, beginning at the
    top of the file.

    Last: Locate the first occurrence of the search string, beginning at the
    bottom of the file.

    Find All: Locate all occurrences of the search string and display them in a
    list box.

See also:

o replace()


ΓòÉΓòÉΓòÉ 9.3.7. Find matching ΓòÉΓòÉΓòÉ

When editing a source file, use this function to locate a matching symbol. To
do this, position your cursor on the symbol for which you want to find the
match.  Select Find matching.  The cursor moves to the matching symbol.

See also:

o Extensions
o goto_matching()


ΓòÉΓòÉΓòÉ 9.3.8. Mark matching ΓòÉΓòÉΓòÉ

Use this function to locate and block text up to a matching symbol.

To locate a matching mark and block the information between two marks,

 1. Position your cursor on the symbol for which you want to find the match.

 2. Select Mark matching.  All of the text between the symbols is blocked.

See also:

o Extensions
o mark_matching()


ΓòÉΓòÉΓòÉ 9.3.9. Mark next matching ΓòÉΓòÉΓòÉ

This option is particularly helpful when working in a nested structure, to help
you move from one nested statement to the next.  To use this option, select
Mark next matching.  From its current position, the cursor moves to the next
occurrence of a set of matching symbols, blocking all of the text between the
symbols.

If you are in a nested structure, selecting this function causes the cursor to
continue to move within the structure from one nested statement to the next,
highlighting the text within the symbols.  When the cursor reaches the
innermost nested statement, selecting this function causes the cursor to move
outside of the nested structure to the next set of matching symbols,
highlighting the text within the symbols.

See also:

o Extensions
o mark_matching_next()


ΓòÉΓòÉΓòÉ 9.3.10. Find routines ΓòÉΓòÉΓòÉ

Use the Find routines option to locate all routines in the current buffer.
PREDITOR/2 currently supports the following extensions:

o .COB

o .CBL

o .C

o .PEL

o .CPP

To find a routine,

 1. Select Find routines. The Find Routines dialog box is displayed. The
    located routines and their line numbers are displayed in this dialog box.

    To perform the actions below, follow the corresponding instructions:

    Move the cursor in the file to a listed occurrence: Highlight the
    occurrence (or use Next and Prev to move the cursor) and click on Goto. or
    Double-click on an item in the list.

    Move the cursor down the list of occurrences: Click on Next.  As you move
    through the list, the highlight bar moves through the file, stopping on the
    line containing the selected occurrence. Click on Goto to position the
    cursor on that line of the file.

    Move the cursor up through the list of occurrences: Click on Prev.  As you
    move through the list, the highlight bar moves through the file, stopping
    on the line containing the selected occurrence. Click on Goto to position
    the cursor on that line of the file.

    Discontinue the Find All process: If there are numerous occurrences to be
    located, this process can be time-consuming.  In this situation, you can
    click on Stop to end the processing.

    Close this dialog box: Click on Close.

    Minimize this dialog box for viewing at a later time: Click on the minimize
    icon in the upper right corner of the dialog box.  The minimized box can be
    viewed by selecting the Dialog list function. See Dialog list for more
    information.

See also:

o routines()
o Extensions


ΓòÉΓòÉΓòÉ 9.3.11. Locate line number ΓòÉΓòÉΓòÉ

Use the Locate line number option to move the cursor to a specified line in
your buffer.

To move the cursor to a specific line,

 1. Select Locate line number from the Search menu. A dialog box is displayed.

 2. Enter the line number to which you want to move. Press [Enter] or click on
    OK The specified line number scrolls to the center of the window.

See also:

o Special keys on prompts
o goto_line()
o goto_pos()


ΓòÉΓòÉΓòÉ 9.3.12. Bookmark list ΓòÉΓòÉΓòÉ

Use the Bookmark list function to select from a list of bookmarks. Bookmarks
represent marked places in your file where you can position your cursor.  You
need to have a bookmark defined before you can use this function.

To select from a list of bookmarks,

 1. Select Bookmark list to display a list of current bookmarks.  The Bookmark
    List dialog box is displayed.

 2. You can choose from the following functions to locate the desired bookmark:

    Move the cursor to a specific bookmark: Select the bookmark from the list
    (or use Next and Prev to move the highlight bar), and click on Goto.

    Move the highlight bar down through the list of bookmarks: .Click on Next.
    As you move through the bookmark list, the line in the file containing the
    selected bookmark is highlighted.

    To perform the following activities, refer to their corresponding
    directions:

    Move the highlight bar up through the list of bookmarks: Click on Prev.  As
    you move through the bookmark list, the line in the file containing the
    selected bookmark is highlighted.

    Delete a bookmark from the list: Highlight it and click on Delete.

    Close the dialog box: Click on Close.

    Minimize the dialog box for viewing at a later time: Click on the minimize
    icon in the upper right corner.  The minimized box can be viewed using the
    Dialog list function.

See also:

o goto_bookmark()
o Dialog list
o place_bookmark()


ΓòÉΓòÉΓòÉ 9.4. Buffers menu ΓòÉΓòÉΓòÉ

Use the Buffers menu to select options that effect the currently open buffers.
You can select from the following options on the Buffers menu:

o Next buffer
o Previous buffer
o Close buffer
o Buffer List


ΓòÉΓòÉΓòÉ 9.4.1. Next buffer ΓòÉΓòÉΓòÉ

All open buffers are displayed in a list (see Buffer List for more
information).  Because each buffer is loaded into a window, there are only as
many buffers displayed as there are windows currently open.  For example, if
you have four buffers open but only two windows open, only two buffers are
displayed.  If the buffer you want is in the buffer list but is not open in
either of the windows, select Next buffer to bring the next buffer into the
current window.

See also:

o buffer_list()
o next_buffer()


ΓòÉΓòÉΓòÉ 9.4.2. Previous buffer ΓòÉΓòÉΓòÉ

Select Previous buffer to go backwards through the buffer list to bring the
previous buffer into the current window.

See also:

o buffer_list()
o prev_buffer()


ΓòÉΓòÉΓòÉ 9.4.3. Close buffer ΓòÉΓòÉΓòÉ

You can close a buffer from the buffer list by first bringing it into a window,
then selecting Close buffer.  You can also close buffers directly from the
buffer list.  See Buffer List for more information on this process.

See also:

o buffer_list()
o delete_buffer()


ΓòÉΓòÉΓòÉ 9.4.4. Buffer list ΓòÉΓòÉΓòÉ

Select Buffer list to view a list of the currently open buffers.  The Buffer
List dialog box is displayed.  If you are in Detached mosde, your buffer list
is displayed on the Control Panel.

After highlighting a buffer from the list, you can use any of the following
buttons:

Read only: Make the buffer read-only.

Delete: Delete the buffer from the buffer list.  This button does not delete
the buffer, but closes it and removes it from the list.

Save: Save the buffer.

Lock: Lock the buffer so that no other users can access the file while you
edit.

Note: If a buffer is listed with (MOD) next to it, it means that the buffer has
been modified without the modifications being saved.  Click on Save to save the
buffer.

When you have completed specifying information in the Buffer List dialog box,
you can either click on OK to save your changes, or click on Cancel to exit the
dialog box without saving any changes.

See also:

o buffer_list()


ΓòÉΓòÉΓòÉ 9.5. Tools menu ΓòÉΓòÉΓòÉ

The Tools menu offers options such as displaying a command dialog box,
accessing the PEL debugger, and accessing the version control system.

From the Tools menu, you can select from the following options:

o Command dialog
o System window
o Compile
o Pel debugger
o Dialog list
o Next
o Previous
o Tags locate
o CTags make
o Peltags make
o Version Control

See also:

o debug()
o invoke_function()


ΓòÉΓòÉΓòÉ 9.5.1. Command dialog ΓòÉΓòÉΓòÉ

Select Command dialog to display a dialog box from which you can issue an
editor command or display the value of a variable. When entering PEL fuctions
to execute do not supply parenthesis around arguments or comma's between them.
Only constant values can be passed as arguments from the command line.

 To get context sensitive help on the text entered in the edit field press
[Ctrl][F1].

To open the Command dialog box,

 1. Select Command dialog.  A dialog box is displayed.

 2. Enter a PEL command or select one from the command history list.  Then
    press [Enter] or click on OK.

See also:

o invoke_function()
o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 9.5.2. System window ΓòÉΓòÉΓòÉ

The System Window option enables you to enter an OS/2 command in an OS/2
window.

To open and use an OS/2 window,

 1. Select System window.  An OS/2 window opens.

 2. Type the command at the command line and press [Enter].

 3. Type EXIT at the command line and press [Enter].  The OS/2 window closes
    and the cursor returns to PREDITOR/2.

See also:

o system()


ΓòÉΓòÉΓòÉ 9.5.3. Compile ΓòÉΓòÉΓòÉ

Select Compile to begin compiling the current buffer.  If you have not yet
specified a compiler for the file extension, a warning message box is
displayed.

Note: You can specify a compiler/extension association in the Settings
Notebook. Compilers for further information.

See also:

o compile_buffer()


ΓòÉΓòÉΓòÉ 9.5.4. Pel debugger ΓòÉΓòÉΓòÉ

The PEL Debugger option provides access to the PEL debugger. Refer to the PEL
Debugger for a complete discussion of the debugger.

See also:

o debug()


ΓòÉΓòÉΓòÉ 9.5.5. Dialog list ΓòÉΓòÉΓòÉ

Certain OS/2 list boxes can be minimized for viewing at a later time.  These
list boxes include Find All, Find Routines, Bookmark List and Compile Results.
The Dialog list option enables you to display minimized dialog boxes.

To display minimized dialog boxes,

 1. Select Dialog list.  The Dialog List dialog box is displayed. To complete
    the following actions, follow the associated instructions:

    Display a hidden list box: Highlight the list box (or use Next and Prev to
    move the highlight bar to the list box) and click on Goto.

    Move the highlight bar down through the list of list boxes: Click on Next.

    Move the highlight bar up through the list of list boxes: Click on Prev.

    Close the dialog box: Click on Close.

See also:

o goto_next_error()


ΓòÉΓòÉΓòÉ 9.5.6. Next ΓòÉΓòÉΓòÉ

The Next option displays the next line in the current dialog.  If you are using
a dialog box containing strings or errors, use this tool to move to the next
item in the list.

See also:

o goto_next_error()


ΓòÉΓòÉΓòÉ 9.5.7. Previous ΓòÉΓòÉΓòÉ

 The Previous option displays the previous line in the current dialog.  If you
are using a list box containing strings or errors, use this tool to move to the
previous item in the list.

See also:

o goto_next_error()


ΓòÉΓòÉΓòÉ 9.5.8. Tags locate ΓòÉΓòÉΓòÉ

Use the Tags locate option to locate source code containing a particular tag.
Before this function can be used, a tags file must be created.  A tags file is
a data file that lists identifiers (function names, variables, etc.) with
information on where each was defined within the source code.

Once your tags file is built, you can use the tags() and tags_auto() functions
to retrieve the appropriate source file, and position the cursor at the
definition. (See CTags make or Peltags make.)

To locate a tag,

 1. Select Tags locate.

 2. Enter the tag (function or variable name) you want to find in the dialog
    box that is displayed.

 3. Press [Enter] or click on OK to find the specified tag.

See also:

o peltags_make()

o tags()

o What are tags?


ΓòÉΓòÉΓòÉ 9.5.9. CTags make ΓòÉΓòÉΓòÉ

Select Ctags make to create a CTAGS.TAG data file for all obvious functions,
structure definitions, and defined macros.  In the dialog box that is
displayed, enter a list of C source file extensions to process.

The ability to quickly view function definitions and constant #defines in C and
C++ is critical for any software developer.  The Ctags make function parses C
and C++ source code files for function names, #defines, typedefs, structure
definitions, and class declarations.  It then saves all of these symbols and
their locations in a file named CTAGS.TAG.  Later, when you want to view the
source code for any of these symbols, call function tags() with the name of the
symbol as a parameter, or call tags_auto() with your cursor placed on the
symbol.  The appropriate file is loaded with the source code visible.

When you run ctags_make(), it reports the date on which the tags file was last
updated, and prompts you for the extensions of the files you want to parse.

Hint:  PREDITOR/2's current working directory must be the directory for which
you want to create the .TAG file, so you should call chdir() first.

Note:  Parsing source files takes a long time, so be prepared to let the editor
run in the background until it is done parsing.  It sounds a tone when
processing is complete.

See also:

o peltags_make()

o tags()

o What are tags?


ΓòÉΓòÉΓòÉ 9.5.10. Peltags make ΓòÉΓòÉΓòÉ

Select the PELtags make option to build a PELTAGS.TAG data file for all
functions and initialized global variables in the current CPE.AE file.

See also:

o peltags_make()

o tags()

o What are tags?


ΓòÉΓòÉΓòÉ 9.5.11. Version Control ΓòÉΓòÉΓòÉ

Select the Version Control option to tailor the version control system to your
preferences. (You must enable the version control system (VCS) before you can
select any of the options available in the system.  Enable the version control
system by selecting the Enable VCS check box on the VCS (Version Control
System) page of the Settings Notebook.)

Get
          Selecting Get enables you to retrieve a file from the version control
          system and at the same time lock the file so that it can not be
          released to another user.  When you select Get, a dialog box is
          displayed showing the Get command.  This command reflects the default
          value from the VCS page of the Settings Notebook.
Put
          Selecting Put releases the lock on the file and returns it to the
          version control system.  When you select Put, a dialog box is
          displayed, showing the Put command.  This command reflects the
          default value from the VCS page of the Settings Notebook.
VDiff
          Select Vdiff to compare two versions of a version control system
          file. The default presents the file from the active buffer and the
          tip (latest) version of that file from the version control system
          library. The results are stored in a buffer and presented in a
          vertically or horizontally divided window. Scrolling is synchronized
          between windows.  Insertions are highlighted in the edited version,
          and deletions are highlighted in the tip version.

To compare two versions of a file,

 1. Select Vdiff.  The PVCS VDIFF dialog box is displayed.

 2. Enter the name of the source file and if necessary, a revision/version
    number, in the Reference fields.

 3. Enter the name of the target file and if necessary, a revision/version
    number in the Target fields.

 4. Select either the Comparison or the Vdiff output radio button in the View
    group box.  These options specify how you want to view the compared
    results.

 5. Use the radio buttons in the Orientation group box to specify how the
    information will be displayed when you view results in comparison mode.

 6. Select or clear the Ignore whitespace check box.  Selecting this box causes
    whitespace from indentation and other space differences to be considered as
    part of the line.  This space can cause unnecessary error notations. Clear
    this box to ignore whitespace.

 7. Click on OK or press [Enter].

See also:

o get_command
o put_command
o vdiff_command
o pvcs()


ΓòÉΓòÉΓòÉ 9.6. Options menu ΓòÉΓòÉΓòÉ

Use Options in the menu bar to tailor the primary Edit environment and toggle
the tool bar and status bar. You can select from the following choices:

o Quick Settings
o Settings Notebook
o Save settings
o Save state
o Colors
o Fonts
o Key bindings
o Toggle toolbar
o Toggle status bar

See also:

o color_dialog()
o toggle_linenumbers()
o toggle_status_bar()
o toggle_toolbar()


ΓòÉΓòÉΓòÉ 9.6.1. Quick Settings ΓòÉΓòÉΓòÉ

Use the Quick Settings item on the Options menu to change some of the editor's
basic settings.  A subset of the Settings Notebook, your Quick Settings are
applied to all buffers, windows, and types, and are made the defaults as
appropriate.

Note: For more detail on a Quick Setting, see the corresponding section in the
Settings Notebook.

The list below describes the preferences you can select on the Quick Settings
dialog box:

o Editor Quick Settings

o Window Quick Settings

o Types Quick Settings

o Buffer Quick Settings


ΓòÉΓòÉΓòÉ 9.6.1.1. Editor Quick Settings ΓòÉΓòÉΓòÉ

From the Quick Settings dialog box, you can specify the following editor
settings:  Refer to the list below for a description of each Editor setting:

Emulation
          From the list box, select the system you want the editor to emulate.
          The emulation mode you choose affects the way your keyboard behaves.

Cursor
          Select "Vertical" for a vertical cursor, or "Horizontal" for a
          horizontal cursor.

Status Bar
          Select "Prompts" to have prompts displayed on the status bar instead
          of in dialog boxes. Select "Dynamic resizing" to resize each field of
          the status bar to display full prompts and messages.

Save
          Select "Create backup on save" to copy the file as it existed before
          modifications.  This file is saved in the backup directory you
          specify in the Settings Notebook, and has the same extension as the
          original file unless the backup directory is the same as that of the
          original file.  In this case, the backup file's extension is .BAK.

          Select "Autosave" to have the editor periodically create a temporary
          copy of your modified buffers.  These copies will be deleted when a
          modified buffer is closed or the editor is exited normally.  You can
          set the time between auto saves in the "Auto save time (min.)" check
          box in the Editor settings notebook


ΓòÉΓòÉΓòÉ 9.6.1.2. Window Quick Settings ΓòÉΓòÉΓòÉ

Window settings that you are likely to change often are in the Windows scope
box.  Refer to the list below for a description of each Window setting:

Mode
          Select either "Single", "Multiple", or "Detached" to indicate how the
          editor displays your windows.  To limit one buffer to each window,
          select "One buffer per window".

Miscellaneous
          Select "Line numbers" to display line numbers in each window. Select
          "Vertical scroll bar" and/or "Horizontal scroll bar" to display these
          scroll bars on your main editor window.


ΓòÉΓòÉΓòÉ 9.6.1.3. Types Quick Settings ΓòÉΓòÉΓòÉ

Types settings that you are likely to change often are in the Types scope box.
Refer to the list below for a description of each Types quick setting:

Type
          From the list box, select the types of files you work with.

Extensions
          Enter the extension associated with the Type you selected in the Type
          pull-down box.

Template expansion
          Select this check box to toggle template expansion on.


ΓòÉΓòÉΓòÉ 9.6.1.4. Buffer Quick Settings ΓòÉΓòÉΓòÉ

Buffer settings that you are likely to change often are in the Buffer scope
box.  Refer to the list below for a description of each Buffer quick setting:

Color highlighting
          Select this check box to enable color highlighting.

Auto indent
          Select this check box to enable auto-indent.

Expand tabs on save
          Select this check box to convert all tabs into spaces when you save
          the file.


ΓòÉΓòÉΓòÉ 9.6.2. Settings Notebook ΓòÉΓòÉΓòÉ

Click on the Settings option to access the Settings Notebook. From the
notebook, you can customize PREDITOR/2 to your specifications.  See Settings
Notebook or Customizing for more information.

See also:

o Editor Settings
o Buffer Settings
o Types
o Window Settings
o File Settings


ΓòÉΓòÉΓòÉ 9.6.3. Save settings ΓòÉΓòÉΓòÉ

Select the Save settings option to save any changes made to the Settings
notebook.

See also:

o save_flags
o SAVE_


ΓòÉΓòÉΓòÉ 9.6.4. Save state ΓòÉΓòÉΓòÉ

When you exit PREDITOR/2, you have the option of taking a "snapshot" of the
state of the editor before you actually exit.  You do this by selecting the
Save state option.  The next time you start the editor, it is loaded in its
previous state.

See also:

o save_flags
o SAVE_


ΓòÉΓòÉΓòÉ 9.7. Colors ΓòÉΓòÉΓòÉ

You can change your basic screen colors in the Color settings dialog box.  To
access this option, select Colors from the Options menu. Note:  For advanced
highlighting, use the Colors page in the Types notebook.

 1. Use the Fields list box to select the element whose color you want to
    change.

 2. Select the Foreground and Background colors by clicking on the appropriate
    colors on the color palette.

 3. Select any of the appropriate option buttons:

    Apply to all--Apply these colors to all open windows.

    Make default--Make these settings the new default settings.

    OK--Save the settings.

    Default--Retrieve the system default color settings.

    Undo--Undo your changes and start over.

    Cancel--Exit this dialog box without saving any changes.

    Help--For help on using the Color dialog box.

See also:

o color_dialog()
o COLOR_
o color_


ΓòÉΓòÉΓòÉ 9.8. Fonts ΓòÉΓòÉΓòÉ

You can change the font type and size from the Font Dialog dialog box.  To
access this option, select Fonts from the Options menu.

 1. Select a font type from the Name drop-down box.

 2. Select a font size from the Size drop-down box.

 3. Select a font style from the Style drop-down box.

 4. Select the Display or Printer check box if you want to view display or
    printer fonts.

 5. In the Emphasis group box, select or clear the Outline, Underline, or
    Strikeout check boxes to enable or disable the desired emphasis.

 6. Select one of the following selection buttons (optional):

    Apply to all--Apply these fonts to all open windows.

    Make default--Make these settings the new default settings.

    OK--Save the settings.

    Default--Retrieve the system default font settings.

    Undo--Undo your changes and start over.

    Cancel--Exit this dialog box without saving any changes.

    Help--For help on using the Font dialog box.

See also:

o font_dialog()


ΓòÉΓòÉΓòÉ 9.9. Key bindings ΓòÉΓòÉΓòÉ

PREDITOR/2's Key Bindings option enables you to assign (bind) your most
commonly-used functions to keystrokes.

To bind a key to a function,

 1. Select Key bindings.

The Key Bindings dialog box is displayed. The Quick keys group box enables you
to easily see all bindings for a particular key or key combination.

To enter a key,

 1. Click on Type a key.  From the dialog box that is displayed, enter the key
    you want to view.  For example, to see all bindings for Shift+Esc, click on
    Type a key, then press [Shift][Esc].

or

Specify the key to be viewed by selecting or clearing the appropriate check
boxes (Ctrl, Shift, Alt, and Num), then using the drop-down box to specify the
rest of the key.

Note: The Num check box will become available only when you select from the
drop-down box a key that appears on the numerical keypad.

 1. Click on Show bindings.  If there are currently any functions bound to this
    key, they are displayed in the Current function group box.  The function is
    also highlighted in the Bindings group box.
 2. Move to the Bindings box and select from the list box the key to which the
    command should be bound. Click on Bind to complete the bind.  If there are
    parameters for the function, enter them in the Parameters field.  Click on
    Function Help to view information on a particular function.
 3. Use the Current keys for group box to view all current keys for a
    particular function.  The function must be highlighted in the Bindings box
    in order for the correct information to appear in the Current keys for box.
 4. Click on one of the buttons listed below when you have finished your key
    bindings:

Click here To

Ok        Exit the dialog box.  You are prompted to save any changes that have
          not yet been saved.

Cancel    Exit the dialog box without saving any changes.

Save      Save changes and continue assigning keys to functions.

To unbind a key from a function,

 1. Highlight the key in the Current keys for drop-down box.

 2. Click on Unbind.


ΓòÉΓòÉΓòÉ 9.10. Toggle toolbar ΓòÉΓòÉΓòÉ

The toolbar, located at the top of the buffer window, appears by default.
However, you can toggle it on and off by selecting or deselecting Toolbar from
the Options pull-down menu. The toolbar contains icons which represent
commonly-used editor functions. Even though these functions can be accessed
through pull-down menus, displaying them on the toolbar offers you a shortcut
to them.

The toolbar can be toggled on and off by selecting or deselecting Toggle
toolbar.

See also:

o toolbar_info()


ΓòÉΓòÉΓòÉ 9.11. Toggle status bar ΓòÉΓòÉΓòÉ

The status bar appears in the editor by default. However, you can toggle it on
and off by selecting or deselecting Status bar from the Options pull-down menu.
The status bar displays information regarding the current editor session.  The
amount and type of information shown in the status bar can be controlled using
the Status Bar notebook settings.

For further information on the status bar, see {*Status bar options in Chapter
2 - Customizing*}.

See also:

o status_bar_flags
o Status Bar


ΓòÉΓòÉΓòÉ 9.12. Window menu ΓòÉΓòÉΓòÉ

The Window menu offers several options that determine what windows are
displayed and how they are arranged.  The options described below reflect the
window options.

o New
o Cascade
o Tile
o Cascade all buffers
o Tile all buffers
o Split horizontal
o Split vertical
o Buffer filter
o Next
o Previous
o Close all
o Toggle hex mode


ΓòÉΓòÉΓòÉ 9.12.1. New ΓòÉΓòÉΓòÉ

Use the New option to open a new window.  If you currently have a window open
containing a buffer (while in MDI mode) and you select New, the new window
displays the current buffer, giving you two windows filled with the same
buffer.  You can retrieve a different buffer in the new window using the buffer
list (select the {*Buffer list*} option from the {*Buffers menu*})or by
selecting Open from the File menu.  (Be sure to deselect the Open buffers in
new window check box.)

See also:

o create_window()


ΓòÉΓòÉΓòÉ 9.12.2. Cascade ΓòÉΓòÉΓòÉ

Select Cascade to arrange the open windows on top of each other, with each
window's title bar remaining visible.

o cascade_buffers()


ΓòÉΓòÉΓòÉ 9.12.3. Tile ΓòÉΓòÉΓòÉ

Select Tile to arrange all of the open windows so that they are tiled.  This
layout enables you to cover all of the available space in the editor window,
and view all of the windows at the same time.

See also:

o tile_buffers()


ΓòÉΓòÉΓòÉ 9.12.4. Cascade all buffers ΓòÉΓòÉΓòÉ

While Cascade arranges only currently open windows and associated buffers,
Cascade all buffers arranges all buffers in the Buffer list, even if it means
opening up windows to put them in.  If, for example, you have two windows open
but you have three buffers in your list, and you select Cascade all buffers,
the editor automatically opens a window for the third buffer, then cascades all
of the windows.

See also:

o cascade_buffers()
o window_cascade()


ΓòÉΓòÉΓòÉ 9.12.5. Tile all buffers ΓòÉΓòÉΓòÉ

Select Tile all buffers to tile all buffers, opening new windows as necessary.
(Refer to Cascade all buffers for additional information.)

See also:

o tile_buffers()
o window_tile()


ΓòÉΓòÉΓòÉ 9.12.6. Split horizontal ΓòÉΓòÉΓòÉ

Split horizontal replaces the current window with two equally sized windows.
The new windows have the same width as the old window but are only half the
height. Both windows have the same current_buffer which is the current_buffer
from the old window.

See also:

o split_window_horizontal()
o split_window_vertical()


ΓòÉΓòÉΓòÉ 9.12.7. Split vertical ΓòÉΓòÉΓòÉ

Split vertical replaces the current window with two equally sized windows.  The
new windows have the same height as the old window but are only half the width.
Both windows have the same current_buffer which is the current_buffer from the
old window.

See also:

o split_window_horizontal()
o split_window_vertical()


ΓòÉΓòÉΓòÉ 9.12.8. Buffer filter ΓòÉΓòÉΓòÉ

You may want to have only certain types of files displayed in a window.  For
example, if you want your .PEL files in one window and your configuration
(.CFG) files in the other, select Buffer filter to restrict (or filter) the
displayed buffers.

To use the buffer filter,

 1. Select Buffer filter from the Windows menu.  A dialog box is displayed.

 2. Type the filter criteria (for example, *.CFG, or *.PEL) in the text field,
    and press [Enter] or click on OK.

See also:

o next_buffer_mask()
o prev_buffer_mask()
o window_name


ΓòÉΓòÉΓòÉ 9.12.9. Next ΓòÉΓòÉΓòÉ

In MDI mode, use the Next option to bring the next open window to the
foreground, thus making the next window in the window list current.

See also:

o next_window()
o prev_window()


ΓòÉΓòÉΓòÉ 9.12.10. Previous ΓòÉΓòÉΓòÉ

In MDI mode, use the Previous option to bring the previous open window to the
foreground, thus making the previous window in the list current.

See also:

o next_window()
o prev_window()


ΓòÉΓòÉΓòÉ 9.12.11. Close all ΓòÉΓòÉΓòÉ

Select Close all to quickly close every window.  (This option is effective both
in MDI and non-MDI modes.)  Even though the windows are closed, the buffers are
still displayed in the buffer list.

See also:

o delete_window()


ΓòÉΓòÉΓòÉ 9.12.12. Toggle hex mode ΓòÉΓòÉΓòÉ

For editing non-text files, you can toggle hex mode with the Toggle hex mode
menu item.  When hex mode is toggled on, your screen contains two columns: the
hex characters at the left, and the matching ASCII characters on the right.

Use the [Tab] key to move between the hex side (on the left) and the character
side (on the right).  Both sides reflect the changes entered, regardless of the
side they were entered into.

To toggle hex editing off, you can press the [Esc] key (in all emulations
except VI and Emacs) or select Toggle hex mode on the Window menu.

Note: Color highlighting and text selection are disabled when hex mode is
toggled on.

See also:

o toggle_dump_mode()


ΓòÉΓòÉΓòÉ 9.13. Help menu ΓòÉΓòÉΓòÉ

Use the Help menu to access the Editor Help library. You can select from the
following choices:

Help index
          Lists all help topics.
General help
          Displays an overview of the editor.
Using help
          Displays instructions for using help.
Keyword help
          Displays help for the keyword at the current cursor position.  If
          help can not be found for the keyword, a "Linking not found" warning
          is issued.
Product information
          Displays the version, copyright, product license number, and customer
          name.

See also:

o display_help()
o display_help_item()
o about_dialog()


ΓòÉΓòÉΓòÉ 9.14. Dialog List ΓòÉΓòÉΓòÉ

This dialog allows you to move through a list of file positions.  The buttons
will become active when a selection from the list has been made.

Available Buttons:

Goto
          Moves the cursor to the postion and buffer defined by the currently
          selected item of the list.
Next
          Moves the cursor to the postion and buffer defined in the next item
          of the list.
Prev
          Moves the cursor to the postion and buffer defined in the previous
          item of the list.
Delete
          From the Bookmark List, this button Deletes the selected bookmark.
Stop
          While performing a compile, this button stops the compiler execution.
Close
          Closes the dialog, removing it from the screen and losing the data.
Help
          Displays this help message.


ΓòÉΓòÉΓòÉ 10. Regular Expressions ΓòÉΓòÉΓòÉ

Regular expressions are special characters in a search value that let you
specify character patterns to match rather than simple sequences of literal
characters.  Regular expressions enable you to:

o Specify a character set or range to be included during a search

o Locate invisible characters such as tabs and carriage returns

o Specify wild card matching (search with *, +, and ?)

o Position the cursor within a search pattern

o Find a string, limiting the search to either the beginning or end of a line

o Match a string using "either/or" logic (alternation)

o Specify match group

o Specify replacement groups.

When editing large files, the use of regular expressions can save time. The
versatility of metacharacters provides unlimited flexibility when applied to
the search and replace process.  Try testing your regular expressions against
sample test data before using with production data.

The following is a list of regular expressions and their meanings.

Expression     Matches
^              Beginning of line
$              End of line
.              Any character except newline
[ ]            Any one of the characters inside [ ]
[^ ]           Any character in [ ] except those that follow the ^
[a-z]          Any character between a and z, inclusive
[a-z-]         Any character between a and z, inclusive and the - character
?              Zero or one character of the preceding class
*              Zero or more characters of the preceding class
+              One or more characters of the preceding class
&              When replacing, append change value to search value.
<              Line up with the begining of a word as defined by
               word_delimiter().
>              Line up with the end of a word as defined by word_delimiter().
|              Either last or next expression
( )            Define a group of expressions
{ }            Define a match group of expressions
\t             Tab character
\n             Newline character
\c             Position cursor after matching
\\             Literal backslash

Many examples may be found in the PREDITOR/2 User's Guide


ΓòÉΓòÉΓòÉ 10.1. What are tags? ΓòÉΓòÉΓòÉ

A tags file is a data file which lists identifiers (function names, variables,
etc.) along with information on where each was defined within the source code.
With a tags file in place, one can use the functions "tags" and "tags_auto"
contained herein to "bring in" the appropriate source file and position the
cursor at the definition.

How does one build a tags file?  In addition to the two tags file building
functions peltags_make() and ctags_make(), several commercial tags file
building utilities exist which quickly build tags files for many languages. The
tags file format used here is compatible with Moderne Software's PC-TAGS(tm)
progam.


ΓòÉΓòÉΓòÉ 10.2. Changing Settings ΓòÉΓòÉΓòÉ

Pages have default settings that you can customize to your preference; for
example, you might want to change your emulation mode or the flags that are
used to do a search.  To view or change the settings:

 1. Click on Settings from the Options menu.
 2. Select the settings you want to change by clicking on one of the tabs on
    the right side of the notebook. (Editor, Window, or Buffer)

You can change the settings on any page of the notebook.  You do not need to
worry about saving the change.  This is done automatically when you exit the
notebook.  There are several buttons at the bottom of each page.  Not all of
the buttons are available on each page. The effects of pressing each button are
described below.

Undo
          Changes the settings back to those that were active before the page
          was displayed.

Default
          Changes the settings to the default settings.  The default settings
          are either editor defined or user defined.  The user can define
          default settings by pressing Make default when available.

Make default
          Saves the settings specified on the current page as default settings
          for later use.

Help
          Displays a help screen for the current notebook page explaining the
          settings in more detail.

Some pages also have an Apply to all check box.  When this is selected, the
current settings on the page are apllied to all of the relevent areas.


ΓòÉΓòÉΓòÉ 11. Mouse Basics ΓòÉΓòÉΓòÉ

 If you prefer to use the mouse as you work, the information in the following
sections describe the mouse activities that PREDITOR/2 supports.

Mouse Actions

Mouse Buttons

Marking Blocks

Positioning the Cursor with the Mouse

Creating Windows


ΓòÉΓòÉΓòÉ 11.1. Mouse Actions ΓòÉΓòÉΓòÉ

If you prefer to work using a mouse, the information in this section describes
the mouse activities associated with PREDITOR/2 supports.

The table below lists the basic mouse activities you can perform using
PREDITOR/2.  The bold type names an activity you might want to perform, while
the following regular type describes the corresponding action to complete the
activity.

Position cursor
          Click in window.

Mark text block
          Click and drag up or down.

Mark column block
          Click and drag while holding [Ctrl].

Mark a single line
          Click and drag across line while holding [Alt].

Mark multiple lines
          Click and drag up or down while holding [Alt].

Select window
          Click in desired window.

Resize window
          Click and drag on window border.

Move window
          Click and drag on window title bar.

Line up or down
          Click on scroll bar arrow.

Page up or down
          Click on the scroll bar above or below the scroll bar slider.

Scroll through buffer (text)
          Drag scroll bar elevator.

Minimize window
          Click on minimize icon.

Maximize window
          Click on maximize icon.

Create window
          Click and drag from bottom left to upper right.


ΓòÉΓòÉΓòÉ 11.2. Mouse Buttons ΓòÉΓòÉΓòÉ

Because PREDITOR/2 is an OS/2-based application, the right mouse button is used
nearly as often as the left.  However, when we do not distinguish between the
buttons to be used, the left button is the default.  When the right button is
to be used, it is clearly indicated.  PREDITOR/2 uses the standard click, drag,
and drop techniques.

If your mouse has three buttons rather than the typical two, you can add
commands for the center button.  Refer to the "User Interface" chapter in the
PEL Functions and Variables by Category manual.


ΓòÉΓòÉΓòÉ 11.3. Positioning the cursor ΓòÉΓòÉΓòÉ

Use the mouse to move the cursor to a new location by positioning the mouse
pointer in the desired location in the window and clicking.  If you click on a
position within the window where the mouse cannot go, the cursor moves to the
closest permissible position to that where you clicked the mouse.

Using the technique described above, you can move the cursor to any location on
the screen, even into another window.  Whatever window the cursor is placed in
becomes the active window.


ΓòÉΓòÉΓòÉ 11.4. Marking Blocks ΓòÉΓòÉΓòÉ

Marking text is useful for deleting or copying large areas of text.  To mark
text, click and drag through the text you want to mark, releasing the mouse
button when you come to the end of the block of text to be marked.  This type
of block is often called a stream selection because the highlighted text flows
from a starting point to an ending point.

You can also mark a block of text without dragging the mouse.  To do this in
CUA, position the cursor at the beginning of the text to be marked.  Move the
mouse pointer to the end of the block of text to be marked, and hold down the
[Shift] key while clicking the mouse.

Marking a Column Block

Sometimes it is necessary to delete only a margin or block indentation while
not disturbing the rest of the text in the line.  This is easily accomplished
by holding down the [Ctrl] key while selecting with the mouse.  This method of
marking text, known as a column block, highlights text column by column, rather
than across entire lines.

Selecting a Full Line Block

Typically when you mark text, wherever the cursor is positioned when you
release the mouse button becomes the end of the block.  In this type of block,
if you want to delete an entire line, you must make sure to drag through the
entire line until you reach the end of the line.  In a full line block, you can
select one or more entire lines easily.  To do this, hold down the [Alt] key
while clicking and dragging.

To mark just one line, hold down [Alt] and drag across a couple of characters
on the line.  The entire line is immediately highlighted.

To mark several lines, hold down [Alt] and drag up or down through the text
until the desired lines are highlighted.

Inclusive vs. Exclusive Blocks

When you mark a block of text, you might notice that the character to which the
mouse points is not included in the block.  This is known as an exclusive block
because it excludes the character at the cursor.  By default, PREDITOR/2 makes
exclusive blocks.  The exception to this is in column marked blocks, which are
always inclusive, meaning that the character at the cursor is included in the
block.


ΓòÉΓòÉΓòÉ 11.5. Creating Windows ΓòÉΓòÉΓòÉ

If you are in MDI mode, you can use the mouse to create a new window.

To create a new window with the mouse,

 1. Position the mouse pointer, in the main PREDITOR/2 window, where you want
    the bottom left corner of the window to be.

 2. Click and drag diagonally in any direction, and release the button to
    complete the new window.

As long as you did not take up the whole window with your new window, you can
make another new window using this technique.  If you have no room left to make
a new window, simply resize your current windows.

Note: When creating a window in this manner, the first corner defined must be
outside any previously defined window.  If it is not, the mouse command will
begin to mark text or perform some other mouse action.


ΓòÉΓòÉΓòÉ 12. Miscellaneous dialogs ΓòÉΓòÉΓòÉ

You can receive more information on the following dialog boxes:

o Special keys on prompts
o Goto bookmark prompt
o Place bookmark prompt
o PVCS Get Dialog
o PVCS Put Dialog
o PVCS VDIFF Dialog


ΓòÉΓòÉΓòÉ 12.1. Special keys on prompts ΓòÉΓòÉΓòÉ

The following keys are useful when working in any dialog box:

[Up arrow]          Previous entry for this prompt

[Down arrow]        Next entry for this prompt

[Page Up]           List all entries made on this prompt.  Some histories are
                    only for the current edit session, but some are saved by
                    PREDITOR/2

[Tab]               Completes the partially typed entry with a match from
                    previous entries.  If more than one match is found, a list
                    box of choices is presented.


ΓòÉΓòÉΓòÉ 12.2. Buffer filter prompt ΓòÉΓòÉΓòÉ

Type a string to be used as a mask in the edit area.  Then press [Enter] or
click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.3. Change output name prompt ΓòÉΓòÉΓòÉ

Enter a new file name for the current buffer.  The buffer is saved under the
new name, and the type information for the new extension is applied.

See also:

o Special keys on prompts
o prompt_history()
o Save as


ΓòÉΓòÉΓòÉ 12.4. Debug query prompt ΓòÉΓòÉΓòÉ

Enter variable whose value you would like to query.  Then press [Enter] or
click on OK

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.5. Prompt dialog ΓòÉΓòÉΓòÉ

Enter the information requested in the edit field.  For the editor to accept
this information and continue, press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.6. Open prompt ΓòÉΓòÉΓòÉ

Type a file name in the edit area.  Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o create_buf_and_win()
o edit_file()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.7. Compile prompt ΓòÉΓòÉΓòÉ

Enter the compile command to be used on the current buffer.  To change the
compiler assigned to the current type, or the default compile command, use the
the Types page of the Settings notebook. Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o compile_buffer()
o prompt_history()
o Types


ΓòÉΓòÉΓòÉ 12.8. Compiler name prompt ΓòÉΓòÉΓòÉ

Enter a compiler name in the edit field. Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()
o Types


ΓòÉΓòÉΓòÉ 12.9. Edit file prompt ΓòÉΓòÉΓòÉ

Type a file name in the edit area, then press [Enter] or click on OK.

See also:

o Special keys on prompts
o create_buf_and_win()
o edit_file()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.10. Emacs bind command to key prompt ΓòÉΓòÉΓòÉ

Enter a command to bind to a key.  (This command may be a named keyboard
macro.) To bind the key, press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.11. Emacs change directory prompt ΓòÉΓòÉΓòÉ

Enter the directory you want to become the new current directory, then press
[Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.12. Emacs filter prompt ΓòÉΓòÉΓòÉ

Enter the operating system command through which to filter the selected region.
Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.13. Emacs prefix rectangle prompt ΓòÉΓòÉΓòÉ

Enter a string to insert on each line at the left edge of the defined
rectangle.  Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.14. Name keyboard macro prompt ΓòÉΓòÉΓòÉ

Enter a string to use as a reference to the last defined keyboard macro. The
macro can then be replayed by name.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.15. Emacs replace buffer prompt ΓòÉΓòÉΓòÉ

Enter the name of the file you want to open.  The specified file replaces the
current buffer in the buffer list. Then press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.16. Emacs prefix line prompt ΓòÉΓòÉΓòÉ

Enter a string to insert at the beginning of each new line.  Then press [Enter]
or click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.17. File grep prompt ΓòÉΓòÉΓòÉ

Type the string to search for, and press [Enter] or click on OK.  All matching
strings in the file list will be found and listed in a dialog list box.

See also:

o Special keys on prompts
o fgrep()
o search()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.18. Function binding prompt ΓòÉΓòÉΓòÉ

Enter the name of a function, and press [Enter] or click on OK.  The editor
will display the keys that are bound to that function.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.19. Goto bookmark prompt ΓòÉΓòÉΓòÉ

Type a bookmark name in the edit area.  To move the cursor to this position,
then press [Enter] or click on OK.

See also:

o Special keys on prompts
o goto_bookmark()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.20. Goto line or mark prompt ΓòÉΓòÉΓòÉ

Type a bookmark name or a linenumber to go to in the edit area, then press
[Enter] or click on OK.

See also:

o Special keys on prompts
o goto_bookmark()
o goto_line()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.21. Grep prompt ΓòÉΓòÉΓòÉ

Type a string to search for press [Enter] or click on OK.  All matching strings
in the current buffer will be found and listed in a dialog list box.

See also:

o Special keys on prompts
o grep()
o search()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.22. Insert prompt ΓòÉΓòÉΓòÉ

Type a file name in the edit area, then press [Enter] or click on OK.

See also:

o Special keys on prompts
o prompt_history()
o read_file()


ΓòÉΓòÉΓòÉ 12.23. Line draw prompt ΓòÉΓòÉΓòÉ

Enter one of the displayed line types in the edit area, then press [Enter] or
click on OK.

See also:

o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.24. Load key file prompt ΓòÉΓòÉΓòÉ

Type a file name in that was used to save keyboard macros, then press [Enter]
or click on OK.

See also:

o Special keys on prompts
o playback()
o prompt_history()
o record()


ΓòÉΓòÉΓòÉ 12.25. Place bookmark prompt ΓòÉΓòÉΓòÉ

Type a bookmark name in the edit area.  To set a bookmark at the current cursor
position with that name, then press [Enter] or click on OK.

See also:

o Special keys on prompts
o place_bookmark()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.26. PEL tags prompt ΓòÉΓòÉΓòÉ

Enter a symbol to be looked up in the .AE file.  If the symbol has multiple
completions, you will be presented with a list.  The file that contains the
symbol definition will be loaded and the cursor positioned on the definition.

See also:

o Special keys on prompts
o peltags()
o peltags_auto()


ΓòÉΓòÉΓòÉ 12.27. Get Dialog ΓòÉΓòÉΓòÉ

The Get command retrieves a file from your version control system.  PREDITOR/2
defaults to a PVCS get command that places a lock on the file.

If you are not using PVCS or do not want a lock, you may modify the command in
the dialog box, or change the default on the VCS page of the Settings notebook.
Change or leave the command as it is, and press [Enter] or click on OK

The file is then retrieved from the version control system.

See also:

o get_command
o Special keys on prompts
o prompt_history()
o VCS (Version Control System)


ΓòÉΓòÉΓòÉ 12.28. Put Dialog ΓòÉΓòÉΓòÉ

The Put command releases the lock on the file and returns it to the version
control system.

The dialog box shows the Put command for your current file.  For example, if
your file is titled "MY_FILE.PEL", and your put_command is "put -u " the
command in the Put dialog box would be  put -u MY_FILE.PEL.  If this command is
accurate, simply press [Enter]  or click on OK  Otherwise, first change the Put
command to your needs.

The default put command may be modified on the VCS page of the Settings
notebook.

The file is returned to the version control system, and accessible to any
participating user.

See also:

o put_command
o Special keys on prompts
o prompt_history()
o VCS (Version Control System)


ΓòÉΓòÉΓòÉ 12.29. VDIFF Dialog ΓòÉΓòÉΓòÉ

The VDIFF compares local files to those in your version control system.

See also:

o prompt_history()
o vdiff_command


ΓòÉΓòÉΓòÉ 12.30. Replace prompt ΓòÉΓòÉΓòÉ

Enter a string to replace the search search string. Then press [Enter] or click
on OK.

 To see a table of Regular expressions press [Ctrl][R].

See also:

o Special keys on prompts
o prompt_history()
o Regular expressions
o replace()


ΓòÉΓòÉΓòÉ 12.31. Search prompt ΓòÉΓòÉΓòÉ

Enter a string to search for, then press [Enter] or click on OK.

 To get a table of Regular expressions press [Ctrl][R].

 To get help on regular expressions press [Ctrl][F1].

See also:

o Special keys on prompts
o prompt_history()
o Regular expressions
o search()


ΓòÉΓòÉΓòÉ 12.32. Tabs prompt ΓòÉΓòÉΓòÉ

Enter new tab stops, then press [Enter] or click on OK.

See also:

o buffer_tabs
o Special keys on prompts
o prompt_history()


ΓòÉΓòÉΓòÉ 12.33. Type name prompt ΓòÉΓòÉΓòÉ

Enter a type name in the edit field.  A type name must be valid for use as part
of a function name.  Below is a list of criteria:

o Can only contain alpha-numeric ascii characters, and the "_" character.
o The first character may not be a number.
Press [Enter] or click on OK to accept your name.

See also:

o Special keys on prompts
o prompt_history()
o Types


ΓòÉΓòÉΓòÉ 12.34. Multiple buffer grep prompt ΓòÉΓòÉΓòÉ

Type a string to search for press [Enter] or click on OK.  All matching strings
in the currently loaded buffers will be found and listed in a dialog list box.

See also:

o Special keys on prompts
o wgrep()
o search()
o prompt_history()


ΓòÉΓòÉΓòÉ 12.35. Write buffer as prompt ΓòÉΓòÉΓòÉ

Enter a file name to save the current buffer under and press [Enter] or click
on OK.

See also:

o Special keys on prompts
o prompt_history()
o write_buffer()


ΓòÉΓòÉΓòÉ 12.36. Write key file prompt ΓòÉΓòÉΓòÉ

Enter a file name to store keyboard macros and press [Enter] or click on OK.

See also:

o Special keys on prompts
o playback()
o prompt_history()
o record()


ΓòÉΓòÉΓòÉ 13. Type Identifiers ΓòÉΓòÉΓòÉ

A type identifier precedes each of the variables and functions listed in the
categories below.  This tells you whether the variable stores a string (str) or
if the function returns an integer (int) value.  Since PEL automatically
determines types, these type identifiers are used for informative purposes
only.  Do not use these identifiers in your programming, as they have no
meaning and serve no purpose in PEL source code.  PEL will keep track of types
for you.

Among the type identifiers used are bufid, fileid, funcid, keymapid, markid and
winid.  These are special integers that identify specific buffers, functions,
keymaps, bookmarks and windows, respectively.  These special integers may not
be intermixed nor substituted with ordinary integers.

In other words, you may not make up values for buffer and window ids and then
use them.  These values must be received from the editor system through their
appropriate creating function.  The any type indicates that the associated
value is not restricted to a particular type, while the void type informs you
that no value is returned.


ΓòÉΓòÉΓòÉ 14. PEL Functions ΓòÉΓòÉΓòÉ

Programming Usage

When programming in the extension language, PEL, this function and variable
look-up is indispensable.  This part of the Library Reference Manual will guide
you in determining everything from what values are allowed as arguments to a
function, to how to interpret the results of the function.

You will find that the editor has substantially more "built-in" or global
variables than most (if not all) editors and editor languages.  These variables
help provide the degree of flexibility and configurability that makes the
editor such an attractive editing environment for programmers.

Most of the variables and functions listed here are primitives.  That is, they
are parts of the editor that are made available to the user.  The balance of
the functions and variables are written in the editor's extension language,
PEL.  Those functions and variables that are defined and written in the
extension language will be found in the source code provided. Function Library
Source You are encouraged to look through the source code to better understand
the functions and variables there, and the extension language in general.  You
may even change the library source code, but you should carefully consider the
consequences before doing so.  The editor relies on the functions described
here to function the way they are described.  Changing the way they operate may
render seemingly unrelated features inoperative.  It is recommended that
instead you make copies of the functions or variables using different names and
modify the new ones rather than the originals.

It is not practical to describe all of the functions defined in the source code
provided.  Those not described may be specific to one or more of the emulation
packages, trivial or subject to change.  When you set out to perform a new
programming task, it is often useful to ask yourself if this is a commonly
required task or one which the software already performs.  If the answer is
yes, the first step is to check this library reference for something you can
use.  If this reference does not yield the desired function, you may find a
similar function you can adapt, if you investigate the function library source
code.

REFERENCE ITEM FORMAT

This section describes the format used for each item described in this library
reference.  It will guide you determining the meaning of each component of the
item description.  We will dissect a variable and a function item listing.

 Function  Items: Let us first consider an example function
description:

fclose()

____________

Purpose: Close the file associated with a handle.

____________

Syntax:  int fclose(fileid handle)

____________

Description:
fclose() closes the file indicated by the handle argument.  The
handle argument must be a file handle created with fopen().

____________

Value returned: fclose() returns a non-zero (TRUE) value
if successful.  Upon failure, zero or FALSE is returned.

____________
Compatibility: Return values differ from those of the like-named C function
supported by major compilers.

____________

See also:  fopen()

Function descriptions begin with the item title line, which is a box containing
the name of the function on the left.  Functions are always followed by left
and right parentheses.  This serves to distinguish a function description from
that of a variable.

Purpose: The body of the description begins with the purpose line.  It
summarizes the job performed by the function in a single line.

Syntax: Following a line containing an underline is the syntax line.  The
syntax line contains a usage synopsis of the function.  The value returned by
the function is indicated by a type identifier to the right of the Syntax:
label.  Since PEL automatically determines types, these type identifiers are
used for informative purposes only.

Note!

Do not use these identifiers in your programming.  These identifiers have no
meaning and serve no purpose in  extension language source code.

Among the type identifiers used are bufid, fileid, funcid, keymapid, markid and
winid.  These are special integers that identify specific buffers, functions,
keymaps, bookmarks and windows respectively.  These special integers may not be
intermixed nor substituted with ordinary integers.

The int identifier signifies a 32 bit signed integer.  The str identifier
denotes a character string.  A character string may contain up to 8000
characters and is not terminated by a NULL but rather may contain NULLS
followed by other characters.  The any type indicates that the associated value
is not restricted to any type, while the void type informs you that no value is
returned.

If the function accepts or requires any arguments, they are shown in italics
between the parentheses of the function.  Arguments not enclosed in square
brackets are required.  Arguments that are enclosed in square brackets may be
omitted.  Nested square brackets are used to indicate what other arguments are
required or permitted when an optional argument is used.

Description: The description portion of the item elaborates on the purpose and
defines the arguments used by the function.  Programming tips and examples are
often included in this component of the item.

Value returned: The value returned by the function is further described in this
part of the item description.  The method of determining if the function has
reached a successful completion is detailed as necessary.  This will assist you
in controlling the flow of your program.

Compatibility:

The compatibility and "see also" components of the item description are
optional, appearing in many but not all descriptions.  The compatibility
component is included when it is useful to note the differences and
similarities between the function described and a like-named C language
function.  The "see also" component appears in the item description to point
out related functions or variables whose description may throw further light on
the subject.

A couple of words that occasionally appear in the title line of the item
description are AWK and PEL.  AWK is used to indicate that the variable or
function has been inherited from the AWK programming language.  The PEL word is
used to identify functions and variables that are defined in the extension
language (PEL) source code.

The last difference between the variable and function item descriptions is that
instead of a synopsis of the syntax used by the function there is a type
declaration.  Once again you are reminded that types are never declared in the
editor's extension language.  These type declarations in the manual serve an
informative purpose only.  If you put a similar declaration in your function
source code you will receive an error from the PEL compiler.


ΓòÉΓòÉΓòÉ 14.1. Bit Manipulation ΓòÉΓòÉΓòÉ

You perform bit-wise operations in PEL by using functions rather than by
operators, as you would in many other languages.  You use them to turn bits on
and off, generally to change the setting of a flag controlling some editor
feature. These functions, described below do not modify the values passed as
arguments but rather return the modified value.

One of the most common tasks requiring bit manipulation is that of modifying
variables such as buffer_flags and window_flags, that store a series of buffer
or window attributes.  The set_flag_bits() function is provided to make this
task more convenient.

^
          Performs a bit-wise AND on two numbers.
not()
          Performs a bit-wise NOT on a number.
or()
          Performs a bit-wise OR on two numbers.
set_flag_bits()
          Modify a bit or bits in a flag variable.
shiftl()
          Shifts the bits of a number to the left.
shiftr()
          Shifts the bits of a number to the right.
xor()
          Performs a bit-wise OR on two numbers.


ΓòÉΓòÉΓòÉ 14.1.1. and() ΓòÉΓòÉΓòÉ

and()   Primitive

Purpose: Performs a bit-wise AND on two numbers.

____________

Syntax:  int and(int num1, int num2)

____________

Description: The and() function compares the bits of the num1 and num2
arguments and derives a third value from them.  The argument values remain
unchanged.

This function operates on 32 bit values. If the arguments are not 32 bit
numbers, they are converted to this form for the purpose of this function.

____________

Value returned:

Each bit in the value returned by the and() function is SET ( 1 ) if the
corresponding bits in both arguments are set.  Otherwise, the bit is RESET ( 0
).


ΓòÉΓòÉΓòÉ 14.1.2. not() ΓòÉΓòÉΓòÉ

not()   Primitive

Purpose: Performs a bit-wise NOT on a number.

____________

Syntax: int not(int num)

____________

Description: The not() function derives a value from the num argument that is
its compliment.  The argument value remains unchanged.

This function operates on a 32 bit value argument. If the argument is not a 32
bit number, it is converted to this form for the purpose of this function.

____________

Value returned: Each bit in the value returned by the not() function is SET ( 1
) only if the corresponding bit in the argument is not set.  Otherwise, the bit
is RESET  ( 0 ).


ΓòÉΓòÉΓòÉ 14.1.3. or() ΓòÉΓòÉΓòÉ

or()   Primitive

Purpose: Performs a bit-wise OR on two numbers.

____________

Syntax: int or(int num1, int num2)

____________

Description: The or() function compares the bits of the num1 and num2 arguments
and derives a third value from them. The argument values remain unchanged.

This function operates on 32 bit values.  If the arguments are not 32 bit
numbers, they are converted to this form for the purpose of this function.

____________

Value returned: Each bit in the value returned by the or() function is SET ( 1
) if the corresponding bit in either argument is set.  Otherwise, the bit is
RESET ( 0 ).


ΓòÉΓòÉΓòÉ 14.1.4. set_flag_bits() ΓòÉΓòÉΓòÉ

set_flag_bits()   PEL

Purpose: Modify a bit or bits in a flag variable.

____________

Syntax: int set_flag_bits(int flag, int mask, int value)

____________

Description: The set_flag_bits() function simplifies the task of changing some
bits of a flag variable while leaving others unchanged.  Flag variables include
buffer_flags, window_flags and their corresponding default_... variables.  In
addition, the search_flags variable falls in this category.

The flag argument is the flag variable or value you wish to modify.  The mask
argument indicates which bits are to be modified and which may be preserved.
The value argument contains the new value for the bits to be changed.  The bits
of mask that are SET ( 1 ) are those that are allowed to change.  The bits of
mask that are RESET ( 0 ) will be "masked off" and will not change.

The mask and value arguments are normally descriptive labels corresponding to
the mask and value desired.  These labels may be obtained from the description
of the variable you are modifying.

____________

Value returned: The value returned by the set_flag_bits() function is the new
value of the flag variable.  Since the flag argument itself is not modified,
this value must be assigned to the flag variable in order to change its value.

____________

Example:

window_flags = set_flag_bits(window_flags, WINDOW_CHARS, WINDOW_HEX)


ΓòÉΓòÉΓòÉ 14.1.5. shiftl() ΓòÉΓòÉΓòÉ

shiftl()   Primitive

Purpose: Shifts the bits of a number to the left.

____________

Syntax: int shiftl(int num, int count)

____________

Description: The shiftl() function derives a new value from the num argument by
shifting its bits to the left.  The number of positions the bits of num are
shifted is indicated by the count argument.  Bits that are shifted beyond the
most significant position, bit 31, are lost.

____________

Value returned: The value returned by shiftl() is the new value derived by
shifting the bits of the num argument.


ΓòÉΓòÉΓòÉ 14.1.6. shiftr() ΓòÉΓòÉΓòÉ

shiftr()   Primitive

Purpose: Shifts the bits of a number to the right.

____________

Syntax: int shiftr(int num, int count)

____________

Description: The shiftr() function derives a new value from the num argument by
shifting its bits to the right. The number of positions the bits of num are
shifted is indicated by the count argument.  Bits that are shifted beyond the
least significant position, bit 0, are lost.

____________

Value returned: The value returned by shiftr() is the new value derived by
shifting the bits of the num argument.


ΓòÉΓòÉΓòÉ 14.1.7. xor() ΓòÉΓòÉΓòÉ

xor()   Primitive

Purpose: Performs a bit-wise OR on two numbers.

____________

Syntax: int xor(int num1, int num2)

____________

Description: The xor() function compares the bits of the num1 and num2
arguments and derives a third value from them.  The argument values remain
unchanged.

This function operates on 32 bit values.  If the arguments are not 32 bit
numbers, they are converted to this form for the purpose of this function.

____________

Value returned: Each bit in the value returned by the xor() function is SET ( 1
) if the corresponding bit in one (and only one) of the arguments is set.  If
the corresponding bit is set in both or neither of the arguments is set, the
bit is RESET ( 0 ).


ΓòÉΓòÉΓòÉ 14.2. Blocks and Bookmarks ΓòÉΓòÉΓòÉ

You can keep track of particular locations within a buffer using bookmarks. A
selected block or region of text is surrounded by two special bookmarks
reserved for that purpose.  Marking locations within a buffer can be useful for
other reasons, too.  It may be useful to mark a location to simplify returning
to that location, or so that a region of text may later be marked as a block.
Bookmarks may even mark a location in virtual space.

Virtual space is the space outside the line boundaries of a buffer or that
space created by a tab expansion.  You can find a more complete description of
virtual space in the "Motion" chapter.

Bookmarks are more than notations of line and column number.  They try to
maintain their association with surrounding text.  Bookmarks move when you
insert, move and delete text.  If you delete the text containing one or more
bookmarks, the bookmarks remain where the text previously appeared.  If you
undo the delete operation later, SPE does not restore the bookmarks to their
previous positions in the text.  Instead, they remain clustered at the
beginning of the restored text.

When you position bookmarks in virtual space, they may have difficulty
remaining associated with the surrounding text if you insert text in that
portion of virtual space.

begin_selection()
          To begin a text selection.
create_mark()
          Place a bookmark at a specified buffer location.
delete_all_marks()
          Undefine all bookmarks previously defined.
delete_mark()
          Dispose of a specified bookmark.
distance_between_marks()
          Tells number of characters between specified marks.
drop_anchor()
          Place a selection mark at the current position.
end_selection
          Ends the current text selection.
hilight_word()
          To highlight the word at the current cursor location
hilight_word_mouse()
          To highlight the word at the current cursor location, suitable for
          use with the mouse
lines_between_marks()
          Tells the number of lines between two bookmarks.
mark_column()
          Reports the column in which a given bookmark occurs.
mark_defined()
          Test to determine if a certain bookmark is in use.
mark_line()
          Reports the line in which a given bookmark occurs.
mark_paragraph()
          Selects the paragraph in which the cursor is found.
marked_region_size()
          Tells size of selected block.
marks_in_buffer()
          Counts the number of bookmarks in use for a buffer.
next_mark()
          Move cursor to the next bookmark in current buffer.
pick_unused_mark()
          Select a bookmark number not currently in use.
place_bookmark()
          Mark a location and buffer for later reference.
prev_mark()
          Move cursor to a previous bookmark in current buffer.
raise_anchor()
          Remove the most recently placed selection marker.
remove_selection()
          To remove the current selection.
selection_mark_bottom()
          To retreive the markid of the bottom corner of the current selection.
selection_mark_top()
          To retreive the markid of the top corner of the current selection.
selection_type()
          To retreive the type of the current selection
set_column_mark()
          Begins a column selection at the current position.
set_exclusive_mark()
          Begins an exclusive selection at the current position.
set_inclusive_mark()
          Begins an inclusive selection at the current position.
set_line_mark()
          Begins a line selection at the current position.
swap_marks()
          Exchange the locations of two bookmarks in the buffer.
toggle_anchor()
          Toggle placement of selection mark at current position.
write_block_key()
          Write block to specified file.
write_marked_block()
          Write the marked block of text to a named file.


ΓòÉΓòÉΓòÉ 14.2.1. begin_selection() ΓòÉΓòÉΓòÉ

begin_selection()   Primitive

Purpose:  To begin a text selection.

____________

Syntax:   begin_selection( [marktype type, [markid mark]] )

____________

Arguments:

o type_of_selection - the type of _SELECTION you want.
o mark - mark to use as the beginning corner of the selection,

Description: This function replaces the old drop_anchor() function, starting a
selection of a particular type.

Note:   Although begin_selection() does return a success/failure code, it will
only fail if the system is out of memory, which should never happen in OS/2.

See also:  end_selection, selection_type()

____________

Value returned:  TRUE  -  selection started FALSE -  selection not started


ΓòÉΓòÉΓòÉ 14.2.2. create_mark() ΓòÉΓòÉΓòÉ

create_mark()   Primitive

Purpose: Place a bookmark at a specified buffer location.

____________

Syntax:  markid create_mark(markid num [, int line, int col])

____________

Description: The create_mark() function places a bookmark at the buffer
location specified by the line and col arguments.  If these arguments are not
supplied, the current line and column position are used.

Values less than one for the col and line arguments are treated as a value of
one.  A value for line higher than the number of lines in the buffer is
converted to the number of the last line in the buffer. However, if the col
value is higher than the number of columns in the indicated line, the marker is
placed beyond the end of the line.

The num argument to this function is a bookmark id number.  This bookmark id
may be either an unused id number or the id of a bookmark already in use.  A
bookmark id of less than 1 will cause this function to fail.

If the num id represents a bookmark already in use, the bookmark is reassigned
to the location specified.

____________

Value returned:

The value returned by the create_mark() function is the numeric id placed at
the specified location.


ΓòÉΓòÉΓòÉ 14.2.3. delete_all_marks() ΓòÉΓòÉΓòÉ

delete_all_marks()   Primitive

Purpose: Undefine all bookmarks previously defined.

____________

Syntax:  int delete_all_marks()

____________

Description: The delete_all_marks() function provides a method of "starting
from scratch" with no defined bookmarks.  This function disposes of all
bookmarks regardless of their origin or purpose.

It is considered good programming practice to ensure that no region of text is
currently selected before executing this function.

____________

Value returned:

The value returned by the delete_all_marks() function is the number of marks
removed.


ΓòÉΓòÉΓòÉ 14.2.4. delete_mark() ΓòÉΓòÉΓòÉ

delete_mark()   Primitive

Purpose: Dispose of a specified bookmark.

____________

Syntax:  markid delete_mark(markid mark)

____________

Description: The delete_mark() function disposes of the bookmark associated
with the bookmark id contained in the mark argument.

Any attempt to remove bookmark 0, the current cursor position, with this
function will have no effect.

This function should not be used to dispose of selection bookmarks created with
the drop_anchor() function.

____________

Value returned:

The value returned by the delete_mark() function is the numeric id of the
bookmark which has been removed.  If the function fails, a zero value is
returned.


ΓòÉΓòÉΓòÉ 14.2.5. distance_between_marks() ΓòÉΓòÉΓòÉ

distance_between_marks()   Primitive

Purpose: Tells number of characters between specified marks.

____________

Syntax:  int distance_between_marks(int mark1, int mark2)

____________

Description: This function is used to discover the number of characters in a
block or region defined by the arguments.  Arguments mark1 and mark2 are both
any previously defined bookmarks.  These bookmarks are specified by the id
assigned to them at the time they were created.  They may be supplied in any
order, regardless of which occurs first in the buffer.

The distance measured includes one of the bookmarks but not both.

____________

Value returned:

The value returned by the distance_between_marks() function is the number of
bytes between the two specified marks.  Tabs count only as a single character.
The value returned will be zero if either of the bookmarks referenced as
arguments is not defined.


ΓòÉΓòÉΓòÉ 14.2.6. drop_anchor() ΓòÉΓòÉΓòÉ

drop_anchor()   PEL

Purpose: Place a selection mark at the current position.

____________

Syntax:  int drop_anchor([int typ [, markid id1 [, markid id2]]])

____________

Description: The drop_anchor() function selects a block of text.  The
boundaries of the selected text are defined by the bookmark arguments id1 and
id2.  The position of id2 then becomes the current cursor position.

A last-in, first-out stack of bookmarks placed with drop_anchor() is
maintained. The most recent selection mark is removed through a call to the
function raise_anchor().  When this is done, the defined block becomes the text
between the current cursor position and the bookmark which preceded it on the
stack.

If the id2 bookmark is not supplied, the text between id1 and the current
position is selected.  If neither of the bookmark arguments are supplied, the
mark is placed at the current position.  The selection type is determined by
the type argument. The possible values for the type argument are the same as
those used by the selection_type() function.  If all arguments are omitted a
type 1 bookmark is placed at the current position.

If id2 does not name a valid bookmark, text is marked from id1 to the current
cursor position.  If id1 is not a valid bookmark, however, the function fails.

____________

Value returned:

The value returned by the drop_anchor() function is non-zero (TRUE) on success.
If an error occurs the function returns zero (FALSE).


ΓòÉΓòÉΓòÉ 14.2.7. end_selection ΓòÉΓòÉΓòÉ

end_selection()   Primitive

Purpose:  Ends the current text selection.

____________

Syntax:  end_selection([markid mark])

Arguments:

o mark  -  mark to use as the ending corner of the selection

____________

Description:  The end_selection function ends the current text selection.

____________

Value returned:  TRUE is returned for success, FALSE for failure.

____________

See also: begin_selection()


ΓòÉΓòÉΓòÉ 14.2.8. hilight_word() ΓòÉΓòÉΓòÉ

hilight_word()   PEL

Purpose:  To highlight the word at the current cursor location

____________

Syntax:   hilight_word()

____________

Arguments:  none

Description:The To highlight the word at the current cursor location function
highlights the word at the current cursor location.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.2.9. hilight_word_mouse() ΓòÉΓòÉΓòÉ

hilight_word_mouse()   PEL

Purpose:  To highlight the word at the current cursor location, suitable for
use with the mouse

____________

Syntax:   hilight_word_mouse()

____________

Arguments:  none

Description: The hilight_word_mouse() function highlights the word at the
current cursor location.  This function is meant to be attached to a mouse
event, such as EVENT_MOUSE_LEFT_CLICK2.

____________

Value returned: None.

____________

See also: attach_event_handler()


ΓòÉΓòÉΓòÉ 14.2.10. lines_between_marks() ΓòÉΓòÉΓòÉ

lines_between_marks()   Primitive

Purpose: Tells the number of lines between two bookmarks.

____________

Syntax: int lines_between_marks(int mark1, int mark2)

____________

Description: The lines_between_marks() function reports the number of lines
between the bookmarks specified by the mark1 and mark2 arguments.  The order in
which these two arguments are specified is not significant.

The function determines the line numbers in which mark1 and mark2 occur.  The
number of lines between the two bookmarks is then arrived at through
subtracting one line number from the other.

____________

Value returned: The value returned by lines_between_marks() is a positive
integer representing the number of lines between the two indicated bookmarks.
If the bookmarks are on the same line or one of the arguments does not
represent a valid bookmark, the function returns zero.  The mark_defined()
function may be used to determine if a bookmark is valid.


ΓòÉΓòÉΓòÉ 14.2.11. mark_column() ΓòÉΓòÉΓòÉ

mark_column()   Primitive

Purpose: Reports the column in which a given bookmark occurs.

____________

Syntax: int mark_column([markid num])

____________

Description: The mark_column() function reports the column number in which the
bookmark identified by the num argument may be found.  This function will fail
if num is not a valid bookmark id.  If the num argument is omitted, the
function returns the column of the selection mark.

____________

Value returned: Upon success, mark_column() returns the line number associated
with the indicated bookmark.  Otherwise, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.2.12. mark_defined() ΓòÉΓòÉΓòÉ

mark_defined()   Primitive

Purpose: Test to determine if a certain bookmark is in use.

____________

Syntax: int mark_defined(markid num)

____________

Description: The mark_defined() function reports whether or not the bookmark
indicated by num is currently in use in the current buffer.

____________

Value returned: If the bookmark is in use, mark_defined() returns a non-zero
value.  If the bookmark has not been defined, or has been defined in another
buffer, a value of zero is returned.


ΓòÉΓòÉΓòÉ 14.2.13. mark_line() ΓòÉΓòÉΓòÉ

mark_line()   Primitive

Purpose: Reports the line in which a given bookmark occurs.

____________

Syntax: int mark_line([markid num])

____________

Description: The mark_line() function reports the line number in which the
bookmark identified by the num argument may be found.  This function will fail
if num is not a valid bookmark id.  If the num argument is omitted, the
function returns the line number of the selection mark.

____________

Value returned: Upon success, mark_line() returns the line number associated
with the indicated bookmark.  Otherwise, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.2.14. mark_paragraph() ΓòÉΓòÉΓòÉ

mark_paragraph()   PEL

Purpose: Selects the paragraph in which the cursor is found.

____________

Syntax: int mark_paragraph()

____________

Description: The mark_paragraph() function drops a selection bookmark at the
end of a paragraph and then moves the cursor to the to the beginning of the
paragraph.  The paragraph is highlighted as a result.

For these purposes a paragraph is defined as any line or lines of text preceded
by a blank line or the beginning of the buffer and followed by a blank line or
the end of the buffer.

If the cursor is not located within a paragraph, the paragraph immediately
following the cursor location is selected.  If there are only blank lines
between the cursor position and the end of the buffer, no selection is made.

____________

Value returned: The value returned by this function is non-zero (TRUE) on
success, and zero (FALSE) if an error occurs.


ΓòÉΓòÉΓòÉ 14.2.15. marked_region_size() ΓòÉΓòÉΓòÉ

marked_region_size()   PEL

Purpose: Tells size of selected block.

____________

Syntax: int marked_region_size()

____________

Description: The marked_region_size() function reports the size of the block
currently highlighted.

____________

Value returned: If the block is of type NORMAL_SELECTION, LINE_SELECTION, or
INCLUSIVE_SELECTION, the return value is equal to the number of characters
included in the block.  This count includes newlines. If the currently marked
region is of type COLUMN_SELECTION, the return value is the area of the block
in text cells.  In this case, if the block contains VIRTUAL SPACE the return
value is not equal to the number of characters in the block. It is the number
of columns occupied by the selection. If no marked region exists, the return
value is zero.


ΓòÉΓòÉΓòÉ 14.2.16. marks_in_buffer() ΓòÉΓòÉΓòÉ

marks_in_buffer()   Primitive

Purpose: Counts the number of bookmarks in use for a buffer.

____________

Syntax: int marks_in_buffer([bufid buffer])

____________

Description: The marks_in_buffer() function reports the number of marks in use
for the buffer indicated by the buffer argument.  The buffer argument is a
buffer id returned by the function used to create the buffer.  If this argument
is omitted or is zero, the current buffer is assumed.

This count includes any marks in use by the system through functions as well as
user-defined bookmarks.  Bookmark 0, which is always the current position,
however, is never included in this count.

____________

Value returned: The value returned by marks_in_buffer() is the number of marks
in use for the buffer indicated. If the specified buffer does not exist, the
function fails and a zero value is returned.

____________

See also:   marks_used


ΓòÉΓòÉΓòÉ 14.2.17. next_mark() ΓòÉΓòÉΓòÉ

next_mark()   Primitive

Purpose: Move cursor to the next bookmark in current buffer.

____________

Syntax: int next_mark()

____________

Description: The next_mark() function moves the cursor to the position of the
first bookmark subsequent to the current position in the buffer.  If there are
no subsequent bookmarks in the buffer, the cursor is not moved.

____________

Value returned: This function returns the bookmark id at which the cursor was
placed, upon successful completion. Otherwise, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.2.18. pick_unused_mark() ΓòÉΓòÉΓòÉ

pick_unused_mark()   Primitive

Purpose: Select a bookmark number not currently in use.

____________

Syntax: int pick_unused_mark()

____________

Description: The pick_unused_mark() function selects a bookmark number not
currently in use.  It does not create a bookmark but merely supplies a number.
This function is useful as an argument to several bookmark functions when you
do not want to redefine an existing bookmark.

____________

Value returned: The pick_unused_mark() function returns the lowest bookmark
number not in use.  If all bookmarks are in use a zero value is returned.


ΓòÉΓòÉΓòÉ 14.2.19. place_bookmark() ΓòÉΓòÉΓòÉ

place_bookmark()   PEL

Purpose: Mark a location and buffer for later reference.

____________

Syntax: void place_bookmark([int n])

____________

Description: The place_bookmark() function drops a bookmark at the current
location and remembers which buffer it is in.  You may then return to the
bookmark from any buffer using the goto_bookmark() function. The function will
prompt for a bookmark number if not supplied and will suggest the next unused
bookmark number.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.20. prev_mark() ΓòÉΓòÉΓòÉ

prev_mark()   Primitive

Purpose: Move cursor to a previous bookmark in current buffer.

____________

Syntax: int prev_mark()

____________

Description: The prev_mark() function moves the cursor to the position of the
previous bookmark nearest to the current position in the buffer.  If there are
no previous bookmarks in the buffer, the cursor is not moved.

____________

Value returned: This function returns the bookmark id at which the cursor was
placed, upon successful completion. Otherwise, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.2.21. raise_anchor() ΓòÉΓòÉΓòÉ

raise_anchor()   PEL

Purpose: Remove the most recently placed selection marker.

____________

Syntax: int raise_anchor()

____________

Description: The raise_anchor() function removes the last bookmark placed by
the drop_anchor() or toggle_anchor() function.  This has the effect of changing
the boundaries of the marked region.

This function shares a last-in, first-out stack of bookmarks with the
drop_anchor() function.  The raise_anchor() function removes the most recently
placed selection mark from this stack and disposes of it.  As a result, the
defined block becomes the text between the current cursor position and the
preceded bookmark on the stack.

If, after the most recently defined bookmark has been removed, there are no
previous bookmarks remaining, there will be no marked region of text. If there
is no bookmark on the stack when raise_anchor() is called, the function will
fail.

____________

Value returned: Upon successful completion, raise_anchor() returns a non-zero
value (TRUE).  If the function fails, a zero value (FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.2.22. remove_selection() ΓòÉΓòÉΓòÉ

remove_selection()   Primitive

Purpose:  To remove the current selection.

____________

Syntax:   remove_selection()

____________

Arguments:  none

Description:

____________

Value returned: FALSE    - there is no current selection otherwise  - the type
of selection removed


ΓòÉΓòÉΓòÉ 14.2.23. selection_mark_bottom() ΓòÉΓòÉΓòÉ

selection_mark_bottom()   Primitive

Purpose:  To retreive the markid of the bottom corner of the current selection.

____________

Syntax:   selection_mark_bottom()

____________

Arguments:  none

Description:

____________

Value returned: The markid of the bottom corner of the current selection


ΓòÉΓòÉΓòÉ 14.2.24. selection_mark_top() ΓòÉΓòÉΓòÉ

selection_mark_top()   Primitive

Purpose:  To retreive the markid of the top corner of the current selection.

____________

Syntax:   selection_mark_top()

____________

Arguments:  none

Description:

____________

Value returned: The markid of the top corner of the current selection


ΓòÉΓòÉΓòÉ 14.2.25. selection_type() ΓòÉΓòÉΓòÉ

selection_type()   Primitive

Purpose:  To retreive the type of the current selection

____________

Syntax:   selection_type()

____________

Arguments:  none

Description:

____________

Value returned: The type of the current selection


ΓòÉΓòÉΓòÉ 14.2.26. set_column_mark() ΓòÉΓòÉΓòÉ

set_column_mark()   PEL

Purpose: Begins a column selection at the current position.

____________

Syntax: void set_column_mark()

____________

Description: The set_column_mark() function begins the selection of a region of
text within column boundaries. Column marking is region type 2.  See the
description of the selection_type() function for a discussion of the region
types available.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.27. set_exclusive_mark() ΓòÉΓòÉΓòÉ

set_exclusive_mark()   PEL

Purpose: Begins an exclusive selection at the current position.

____________

Syntax: void set_exclusive_mark()

____________

Description: The set_exclusive_mark() function begins the selection of a region
of sequential characters which excludes the character at the cursor. Exclusive
marking is region type 1.  See the description of the selection_type() function
for a discussion of the region types available.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.28. set_inclusive_mark() ΓòÉΓòÉΓòÉ

set_inclusive_mark()   PEL

Purpose: Begins an inclusive selection at the current position.

____________

Syntax: void set_inclusive_mark()

____________

Description: The set_inclusive_mark() function begins the selection of a region
of sequential characters that includes the character at the cursor.  Inclusive
marking is region type 4.  See the description of the selection_type() function
for a discussion of the region types available.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.29. set_line_mark() ΓòÉΓòÉΓòÉ

set_line_mark()   PEL

Purpose: Begins a line selection at the current position.

____________

Syntax: void set_line_mark()

____________

Description: The set_line_mark() function begins the selection of a region of
sequential lines.  This is region type 3.  See the description of the
selection_type() function for a discussion of the region types available.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.30. swap_marks() ΓòÉΓòÉΓòÉ

swap_marks()   Primitive

Purpose: Exchange the locations of two bookmarks in the buffer.

____________

Syntax: int swap_marks([markid mark1, [markid mark2]])

____________

Description: The swap_marks() function swaps the locations of the bookmarks
represented by arguments mark1 and mark2.  If no arguments to this function are
supplied, then it is assumed that the mark defining the currently marked region
of text is to be swapped with the current cursor position.  When used in this
manner, the function will fail if no region of text has been defined.

If the mark1 argument is supplied but mark2 is not, bookmark 0 is the assumed
value of mark2.  The current position, which is always bookmark 0, may thus be
exchanged with any bookmark using this function.

This is particularly useful when you wish to change the location at which a
marked block begins but maintain the current position as the end of the block.

If either of the arguments names or assumes a non- existent bookmark, the
function will fail.

____________

Value returned: On successful completion, swap_marks() returns a non-zero value
(TRUE).  Upon failure a zero value (FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.2.31. toggle_anchor() ΓòÉΓòÉΓòÉ

toggle_anchor()   PEL

Purpose: Toggle placement of selection mark at current position.

____________

Syntax: int toggle_anchor([int type])

____________

Description: The toggle_anchor() function places a selection bookmark of the
type described in the type argument at the current position if no block is
already marked in the current buffer.  If a selection marker of any type
already exists in the buffer, it is removed.

The possible values for the type argument are the same as those used by the
selection_type() function described above.  If the type argument is omitted,
the normal, type 1, bookmark is assumed.

If a new bookmark is placed, the new bookmark defines a marked block or region
of text as described in the description of drop_anchor().

____________

Value returned: The value returned by the toggle_anchor() function is non-zero
(TRUE) if a bookmark was created and zero (FALSE) if a bookmark was removed.

____________

See also:   drop_anchor(), raise_anchor(), selection_type().


ΓòÉΓòÉΓòÉ 14.2.32. write_block_key() ΓòÉΓòÉΓòÉ

write_block_key()   PEL

Purpose: Write block to specified file.

____________

Syntax: void write_block_key()

____________

Description: The write_block_key() function writes a marked block or, if no
block is marked, the entire buffer to a file.  The name of the tile to be
written is obtained by prompting.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.2.33. write_marked_block() ΓòÉΓòÉΓòÉ

write_marked_block()   Primitive

Purpose: Write the marked block of text to a named file.

____________

Syntax: int write_marked_block(str name)

____________

Description: The write_marked_block() function saves the marked block of text
in the current buffer to the file described in the name argument.

The name argument is a filename and optional path element.  If this argument
contains no path element the default drive and directory are assumed.  If the
file designated by name already exists, it is overwritten without warning.
Supplying a name argument does not change the name of the buffer or the
buffer's default output filename.

The current buffer must contain a marked block of text for this function to
succeed.  If the BUFFER_EXPAND_TABS bit is set in the buffer_flags variable,
tabs are expanded on output.

____________

Value returned: Upon successful completion the value returned by
write_marked_block() is the number of characters written to file.  If an error
occurs, a zero value is returned.  A marked block can never contain zero
characters.

If no block in the current buffer has been marked a message to that effect is
displayed.  Consult the errno variable to determine the cause of other errors.


ΓòÉΓòÉΓòÉ 14.3. Buffers ΓòÉΓòÉΓòÉ

The functions in this category allow you to manipulate  and their contents.
Using these functions, you may create and delete buffers, move from one buffer
to another, or save the contents of a buffer.

When a new file is to be edited, the usual starting place is the edit_file()
function.  This function uses several of the other functions in this category
and the Windowing category to create a buffer and read the file into the
buffer. It then attaches the current window to the buffer so that the contents
may be viewed.  If you wish to create a similar function to fill your needs,
you may construct such a function from create_buffer(), create_window() and
attach_window_buffer().

ai()
          Turns auto-indent feature on or off.
auto_indent_cr()
          To insert a new line and auto-indent
auto_indent_nl()
          To open a new line and auto-indent
browse_file()
          To browse a file in Read-Only mode.
buffer_in_window()
          To find the next window that is attached to a specified buffer, if
          one exists.
buffer_insert_string()
          Insert a string into the specified buffer.
buffer_is_modified()
          Tells if contents of buffer have changed.
buffer_line_exists()
          Tells if a line exists in buffer.
buffer_views()
          Tells number of windows that view a buffer.
change_output_name()
          Obtains new filename for the current buffer.
compare_buffers()
          To compare two buffers
create_buf_and_win()
          To create a new buffer in a new window.
create_buf_and_win_key()
          To create a new buffer in a new window, as appropriate for key
          assignment.
create_buffer()
          Creates a new buffer attached to a disk file.
delete_buffer()
          Disposes of a previously created edit buffer.
delete_buffer_key()
          Removes buffer, does not make system buffer current.
display_filename()
          Display the buffer filename as reminder.
dos_edit()
          Switch editor into DOS newline mode.
edit_file()
          Opens a new buffer and assigns it to current window.
edit_file_key()
          Enhanced function to open new buffer.
edit_unix_file_key()
          Enhanced function to load a UNIX file into a buffer.
next_buffer()
          Make a subsequent buffer on the list the current buffer.
next_buffer_key()
          To make the next buffer current, as suitable for key assignment.
next_buffer_mask()
          To make the next buffer that matches the current window's buffer mask
          the current buffer.
open_file_under_cursor()
          To open the file at the current cursor location.
organize_buffers()
          Displays an icon for each buffer defined.
prev_buffer()
          Make a preceding buffer on the list the current buffer.
prev_buffer_key()
          To make the previous buffer current, as suitable for key assignment.
prev_buffer_mask()
          To make the previous buffer that matches the current window's buffer
          mask the current buffer.
print_buffer()
          Immediately prints the current buffer
read_buffer()
          read a portion of the buffer into a string.
read_file()
          Read a file into the current position of current buffer.
read_file_key()
          Enhanced function to insert file.
tabs()
          Allows defining tab stops interactively.
toggle_buffer_eol()
          Convert the current buffer from DOS to UNIX, or UNIX to DOS end of
          line characters.
toggle_buffer_flags()
          Changes the value of the buffer_flags variable.
toggle_unix()
          Toggles the editor between using DOS and UNIX end of line characters
          when loading buffers.
transfer()
          Transfer text to the current buffer from another buffer.
unix_edit()
          Switch editor into UNIX newline mode.
write_all_buffers()
          Save the edits in modified buffers to their disk files.
write_buffer()
          Writes the contents of the current buffer to disk.
write_buffer_key()
          Saves a buffer if it is modified.


ΓòÉΓòÉΓòÉ 14.3.1. ai() ΓòÉΓòÉΓòÉ

ai()   PEL

Purpose: Turns auto-indent feature on or off.

____________

Syntax:  void ai([int on])

____________

Description: The ai() function is a tersely named synonym for
toggle_auto_indent(), suitable for executing through the PEL interpreter ( ).
If the on argument is zero, the auto-indent feature is turned off, otherwise it
is turned on.  If the argument is omitted this function toggles the current
state of auto-indent mode.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.2. auto_indent_cr() ΓòÉΓòÉΓòÉ

auto_indent_cr()   PEL

Purpose:  To insert a new line and auto-indent

____________

Syntax:   auto_indent_cr()

____________

Arguments:  none

Description: The auto_indent_cr() function inserts and auto_indents a new line.
This function succeeds only if the auto_indent_mode variable is on.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.3. auto_indent_nl() ΓòÉΓòÉΓòÉ

auto_indent_nl()   PEL

Purpose:  To open a new line and auto-indent

____________

Syntax:   auto_indent_nl()

____________

Arguments:  none

Description: This will only work if auto_indent_mode is on.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.4. browse_file() ΓòÉΓòÉΓòÉ

browse_file()   PEL

Purpose:  To browse a file in Read-Only mode.

____________

Syntax:   browse_file( str filename )

____________

Arguments:

o filename - the file to browse

Description: This function is a useful utility when you wish to look at the
contents of a file without the possibility of accidentaly modifying it.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.5. buffer_in_window() ΓòÉΓòÉΓòÉ

buffer_in_window()   Primitive

Purpose:  To find the next window that is attached to a specified buffer, if
one exists.

____________

Syntax:   buffer_in_window( str filespec )

____________

Arguments:

o filespec - the filename of the buffer being looked for.

Description: This function is used when you have the "Open files in new window"
box checked in the open file dialog.  When you select a file to open,
buffer_in_window() is called to see if that file is already loaded in a buffer
in a window.  If it is, instead of displaying that buffer in the current
window, the window that is already displaying that buffer is made current.

____________

Value returned: If the buffer specified is attached to a window, the return is
that window, otherwise, 0.


ΓòÉΓòÉΓòÉ 14.3.6. buffer_insert_string() ΓòÉΓòÉΓòÉ

buffer_insert_string   Primitive

Purpose:  Insert a string into the specified buffer.

____________

Syntax:   buffer_insert_string(bufid buffer, str format, [any arg...])

____________

Arguments:

o buffer - buffer id of the buffer to modify
o format - format string
o [arg...] - optional list of arguments to fill in format string

Description: The buffer_insert_string() function inserts a string into the
specified.  It works the same way as insert_string() except that a buffer other
than the current buffer can be modified.

____________

Value returned: The function returns the inserted string or an empty string if
an error occurred.


ΓòÉΓòÉΓòÉ 14.3.7. buffer_is_modified() ΓòÉΓòÉΓòÉ

buffer_is_modified()   PEL

Purpose: Tells if contents of buffer have changed.

____________

Syntax:  int buffer_is_modified()

____________

Description: The buffer_is_modified() function reports whether the contents of
the current buffer have been changed since the last save operation.  This is
done by examining the buffer's buffer_flags variable.

____________

Value returned: This function returns TRUE ( 1 ) if the current buffer has been
modified. Otherwise, it returns FALSE ( 0 ).


ΓòÉΓòÉΓòÉ 14.3.8. buffer_line_exists() ΓòÉΓòÉΓòÉ

buffer_line_exists()   Primitive

Purpose: Tells if a line exists in buffer.

____________

Syntax:  int buffer_line_exists(int linenum)

____________

Description: The buffer_line_exists() function reports whether a specified line
exists in the current buffer.  The linenum argument specifies the line about
which the inquiry is being made.

____________

Value returned:

If the line exists, a non-zero (TRUE) value is returned.  Otherwise, zero
(FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.3.9. buffer_views() ΓòÉΓòÉΓòÉ

buffer_views()   Primitive

Purpose: Tells number of windows that view a buffer.

____________

Syntax:  int buffer_views([bufid buffer])

____________

Description: The buffer_views() function identifies the number of windows that
are presently attached to a buffer.  The buffer that is the subject of this
inquiry is indicated by the buffer argument.  If this argument is omitted, the
function reports the number of windows attached to the current buffer.

____________

Value returned:

The value returned by the buffer_views() function is the number of windows
associated with the specified buffer.  This number includes any windows not
currently visible on the screen.


ΓòÉΓòÉΓòÉ 14.3.10. change_output_name() ΓòÉΓòÉΓòÉ

change_output_name()   PEL

Purpose: Obtains new filename for the current buffer.

____________

Syntax:  void change_output_name([str filename])

____________

Description: The change_output_name() function assigns a new output filename to
a buffer.  If the new filename is not provided, the editor prompts the user for
the new name.  This name is assigned to the current buffer's buffer_name and
buffer_filename variables.

This function does not immediately cause the buffer to be saved under the new
filename.  When next the changes in the buffer is saved to disk, they will be
saved in a file by this name.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.11. compare_buffers() ΓòÉΓòÉΓòÉ

compare_buffers()   PEL

Purpose:  To compare two buffers

____________

Syntax:   compare_buffers( [bufid buf1, [bufid buf2]] )

____________

Arguments:

o buf1 - the file name of the first buffer to compare
o buf2 - the file name of the second buffer to compare

Description: This function will compare the contents of two buffers and
position the cursor of each buffer at the first difference it find between the
buffers, or if they are identical, at the end of each buffer.  The comparison
starts at the current location of the cursor in each buffer. If the buf1 and
buf2 parameters are not specified, the current buffer and next_buffer() will be
compared.  If the parameters are specified, the files will be loaded into
buffers if they are not already loaded.

____________

Value returned: TRUE  -  input parameters are valid FALSE -  input parameters
are invalid


ΓòÉΓòÉΓòÉ 14.3.12. create_buf_and_win() ΓòÉΓòÉΓòÉ

create_buf_and_win()   PEL

Purpose:  To create a new buffer in a new window.

____________

Syntax:   create_buf_and_win( str name, [long behindwin, long x, long y, long
width, long height])

____________

Arguments:

name - the filename to load into a buffer.
x - x position in pixels of new window, if created.
y - y position in pixels of new window, if created.
width - with in pixels of new window, if created.
height - height in pixels of new window, if created.

Description: This function will create a new buffer that is attached to a new
window.  If the buffer is already attached to a window it will bring that
window to the top.

____________

Value returned: TRUE  -  the buffer was loaded FASLE -  the file could not be
loaded


ΓòÉΓòÉΓòÉ 14.3.13. create_buf_and_win_key() ΓòÉΓòÉΓòÉ

create_buf_and_win_key()   PEL

Purpose:  To create a new buffer in a new window, as appropriate for key
assignment.

____________

Syntax:   create_buf_and_win_key()

____________

Arguments:  none

Description: See creat_buf_and_win()

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.14. create_buffer() ΓòÉΓòÉΓòÉ

create_buffer()   Primitive

Purpose: Creates a new buffer attached to a disk file.

____________

Syntax:  bufid create_buffer(str name, str file [, int b_flags])

____________

Description: The create_buffer() function creates a new buffer and initializes
the associated variables to the current editor system defaults.  The file to
which it is attached is then read into the buffer.

The value of the name argument is assigned to the buffer's buffer_name
variable.  The argument file is used as the initial value for both the
buffer_filename and buffer_original_filename variables.

The newly created buffer is inserted into the buffers list in the position
immediately following the currently active buffer.  It may be made the
currently active buffer by assigning it to the current window or through a call
to the next_buffer() function.

If the file to be attached to the new buffer is already attached to an existing
buffer, the user is notified and permission to proceed is obtained before
creating the buffer.

It is possible to have two writable buffers simultaneously attached to the same
file. In this situation edits made in one buffer are not reflected in the
other.  Operating in this manner is fraught with pitfalls. As a consequence, it
is preferable to open another window onto the original buffer.

However, if you find it desirable to have the same file in two separate buffers
you may do this by making one of the buffers a system buffer.  This requirement
assures that the system buffer will not accidently be written to disk by
write_all_buffers() or similar function.  It must be explicitly written to
disk.

Normally, various buffer attributes are inherited from default_buffer_flags.
This value is then stored in the buffer's buffer_flags variable.  If the
b_flags argument is supplied, however, the value of that argument is used for
buffer_flags instead of using default_buffer_flags. This is useful when you
wish to create a buffer with other than the usual attribute flags.  This is the
accepted method of creating a system buffer or buffer with no undo-redo
capability.  See the description of buffer_flags for a description of the
attributes controlled by the b_flags argument.

System buffers need not be associated with any file.  For this reason, the file
argument may be specified as "", an empty string, when creating a system
buffer.

The higher level function edit_file(), which calls this routine, may be used as
an alternative to this function.

____________

Value returned:

create_buffer() returns the numeric id that the editor system has given to the
newly created buffer.  This id should be stored for later use but never
modified.

If the function fails, usually due to an invalid file argument, a zero value is
returned.  The function will also fail if the named file is already open as a
result of a call to fopen().

____________

See also:  buffer_filename,


ΓòÉΓòÉΓòÉ 14.3.15. delete_buffer() ΓòÉΓòÉΓòÉ

delete_buffer()   Primitive

Purpose: Disposes of a previously created edit buffer.

____________

Syntax:  int delete_buffer([bufid buffer])

____________

Description: The delete_buffer() function removes the buffer identified by the
buffer argument from the editor system.  The buffer argument is the numeric id
returned by the function used to create the buffer.  If the buffer argument is
not supplied, the current buffer is deleted.

Whenever the current buffer is deleted the next buffer in the buffer list
becomes current.  If a window was attached to the deleted buffer, the window is
reassigned to the next buffer in the buffers list.  When deleting both the
current buffer and the current window the buffer should be deleted first.  If
the window is deleted first the current buffer will change, often resulting in
the wrong buffer being deleted.

If there are no more buffers in the buffers list, the buffer may be deleted but
the editor will create a new empty one in its place.  Any windows assigned to
the last buffer are reassigned to the new buffer.

This new buffer will receive the name "Scratch" and it's buffer_flags variable
will be set to indicate that it is a system buffer and is not writable.  The
editor uses this same default buffer when the editor is invoked without
indicating a file to be edited.

____________

Value returned: When successful, delete_buffer() returns a non zero or TRUE
value.  Upon failure, this function returns zero (FALSE).


ΓòÉΓòÉΓòÉ 14.3.16. delete_buffer_key() ΓòÉΓòÉΓòÉ

delete_buffer_key()   PEL

Purpose: Removes buffer, does not make system buffer current.

____________

Syntax:  void delete_buffer_key()

____________

Description: Like delete_buffer(), the delete_buffer_key() function deletes the
current buffer.  However, if the next buffer in the buffer list is a system
buffer, delete_buffer_key() does not allow it to become the current buffer as
the delete_buffer() function would.  Instead, this function makes the next
normal buffer current.  If there is no other normal buffer, the "Scratch"
buffer is created. This behavior makes delete_buffer_key() more suitable for
assignment to a key than its relative, delete_buffer().

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.17. display_filename() ΓòÉΓòÉΓòÉ

display_filename()   PEL

Purpose: Display the buffer filename as reminder.

____________

Syntax:  void display_filename()

____________

Description: The display_filename() shows the output filename associated with
the current buffer in the dialog window.  It is largely intended for use after
operations that change the current buffer or its filename.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.18. dos_edit() ΓòÉΓòÉΓòÉ

dos_edit()   PEL

Purpose: Switch editor into DOS newline mode.

____________

Syntax:  void dos_edit([int convertCurrent])

____________

Description: This function changes the editor's default newline sequence to the
DOS newline sequence. This will affect all subsequent files that are opened.
If the optional parameter changeCurrent is supplied and not zero, the current
buffer will be closed and reopened to allow the changes to take affect.  You
may need to call this function if your default_buffer_eol_string is not set for
DOS files and you want to load a DOS file.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  unix_edit(), edit_unix_file_key(), toggle_unix(),
toggle_buffer_eol()


ΓòÉΓòÉΓòÉ 14.3.19. edit_file() ΓòÉΓòÉΓòÉ

edit_file()   Primitive

Purpose: Opens a new buffer and assigns it to current window.

____________

Syntax:  bufid edit_file([str file])

____________

Description: The edit_file() function creates a new buffer using the
create_buffer() function and then assigns it to the currently active window
with the attach_window_buffer() function.

The file argument contains the name of the file from which data is read into
the new buffer.  This filename therefore becomes the value assigned to the
buffer_filename and the buffer_original_filename for the new buffer.  If this
argument is omitted, the user is prompted for this value.

The file argument is also used to define the value of the buffer_name.  The
buffer_name will be the same as buffer_original_filename except that it will
contain no path element.

Since edit_file() assigns the buffer it creates to the current window, the new
buffer is always the currently active buffer upon completion of the function.
To return to the buffer that was active prior to the call to edit_file(),
execute the prev_buffer() function.

It is possible to edit the same file in two different buffers, though this is
not advisable.  See create_buffer() above for a more complete discussion of
this topic.

____________

Value returned:

edit_file() returns the numeric id that the editor system has given to the
newly created buffer.  This id should be stored for later use but never
modified.

If the function fails, usually due to an invalid file argument, a zero value is
returned.


ΓòÉΓòÉΓòÉ 14.3.20. edit_file_key() ΓòÉΓòÉΓòÉ

edit_file_key()   PEL

Purpose: Enhanced function to open new buffer.

____________

Syntax:  void edit_file_key()

____________

Description: Like edit_file(), the edit_file_key() function prompts for the
name of new file to edit.  It provides some additional assistance in selecting
the new file:  It has a history mechanism that displays the names of files
previously selected when up or down arrows are pressed.  It also will display a
list of files matching a specified pattern when  is pressed (rather than  ).  A
file may then be selected from the list. This function is used whenever
reasonable in the emulation modes provided.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.21. edit_unix_file_key() ΓòÉΓòÉΓòÉ

edit_unix_file_key()   PEL

Purpose: Enhanced function to load a UNIX file into a buffer.

____________

Syntax:  void edit_unix_file_key([str name])

____________

Arguments: name - The name of the UNIX file to load.  If no name is specified
then you will be prompted for a filename.

Description: The edit_unix_file_key() is similar to edit_file_key() except that
the file will be loaded assuming the newline sequence is '\n' (which is the
UNIX standard) instead of '\r\n' (which is the DOS and OS/2 standard).

If the file has already been loaded into a buffer with the wrong newline
sequence, use the function toggle_buffer_eol() to convert it.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  toggle_unix(), dos_edit(), unix_edit(), toggle_buffer_eol()


ΓòÉΓòÉΓòÉ 14.3.22. next_buffer() ΓòÉΓòÉΓòÉ

next_buffer()   Primitive

Purpose: Make a subsequent buffer on the list the current buffer.

____________

Syntax: bufid next_buffer([str pattern [, int include_sys]])

____________

Description: The next_buffer() function may be used in two ways, depending on
whether the pattern argument is supplied.  In either case, next_buffer() is
used to change the currently active buffer.  When the pattern argument is not
present, next_buffer() may be used to increment forward through the buffers
list.

When pattern is supplied, next_buffer() will jump forward in the buffers list
to a buffer whose buffer_name matches the pattern argument.  The pattern
argument may contain wildcard characters as described in the "Filename
Matching" section of "Settling In" chapter of the User's Manual.  Either of the
following examples may be used to increment through the list of user buffers:

  next_buffer()

  next_buffer("")

If the pattern argument has been specified, you may optionally supply the
include_sys argument also. This argument is used to tell next_buffer() to
include system buffers in the buffers list. Normally, there is no need to
access system buffers since they are created and maintained for the use of the
editor.  If you find the need, however, you may access system buffers by
supplying a non-zero value as the include_sys argument.  You may then increment
through the buffers list until you locate the system buffer of interest.  The
following example increments through the list of all buffers:

  next_buffer("",1)

The current buffer is the last to be compared to the pattern argument.

____________

Value returned: This function returns the numeric id of the buffer it makes
current.  This function cannot fail. If either pattern does not match any
subsequent buffers or there is only one buffer in the list the current buffer
remains current.  In this case the id of the current buffer is returned.

____________

See also:   prev_buffer()


ΓòÉΓòÉΓòÉ 14.3.23. next_buffer_key() ΓòÉΓòÉΓòÉ

next_buffer_key()   PEL

Purpose:  To make the next buffer current, as suitable for key assignment.

____________

Syntax:   next_buffer_key()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.24. next_buffer_mask() ΓòÉΓòÉΓòÉ

next_buffer_mask()   PEL

Purpose:  To make the next buffer that matches the current window's buffer mask
the current buffer.

____________

Syntax:   next_buffer_mask()

____________

Arguments:  none

Description: This function differs from next_buffer_key() in that it will
insure that the next buffer honors the buffer mask of the current window.  If a
buffer mask has not been set for the current window, this function will operate
identically to next_buffer_key().

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.25. open_file_under_cursor() ΓòÉΓòÉΓòÉ

open_file_under_cursor()   PEL

Purpose:  To open the file at the current cursor location.

____________

Syntax:   open_file_under_cursor( [str filename] )

____________

Arguments:

o filename -  optional filename to open, otherwise opens file at the curren
  cursor location

Description: This function searches through your INCLUDE, PATH, and DPATH
environment variables for either the file specified or the file at the current
cursor location.  If you set your INCLUDE environment variable to your project
directories, this function would save you the time of typing in paths for the
project files you wish to load.

____________

Value returned: TRUE  -  file successfully opened FALSE -  file not
successfully opened


ΓòÉΓòÉΓòÉ 14.3.26. organize_buffers() ΓòÉΓòÉΓòÉ

organize_buffers()   PEL

Purpose: Displays an icon for each buffer defined.

____________

Syntax: void organize_buffers()

____________

Description: The organize_buffers() function defines a window for each buffer
in use and then displays them in rows as icons.  This can be useful when
working with a large number of buffers.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.27. prev_buffer() ΓòÉΓòÉΓòÉ

prev_buffer()   Primitive

Purpose: Make a preceding buffer on the list the current buffer.

____________

Syntax: bufid prev_buffer([str pattern [, int include_sys]])

____________

Description: The prev_buffer() function may be used in two ways, depending on
whether the pattern argument is supplied.  In either case, prev_buffer() is
used to change the currently active buffer.

When the pattern argument is not present, prev_buffer() may be used to
increment backward through the buffers list.

When pattern is supplied, prev_buffer() will jump backwards in the buffers list
to a buffer whose buffer_name matches the pattern argument.  The pattern
argument may contain wildcard characters as described in the "Filename
Matching" section of "General Operation" chapter of the User's Manual.

If the pattern argument has been specified, you may optionally supply the
include_sys argument also. This argument is used to tell prev_buffer() to
include system buffers in the buffers list. Normally, there is no need to
access system buffers since they are created and maintained for the use of the
editor.  If you find the need, however, you may access system buffers by
supplying a non-zero value as the include_sys argument.  You may then increment
through the buffers list until you locate the system buffer of interest.

The current buffer is the last to be compared to the pattern argument.

____________

Value returned: This function returns the numeric id of the buffer it makes
current.  This function cannot fail.  If either pattern does not match any
subsequent buffers or there is only one buffer in the list the current buffer
remains current.  In this case the id of the current buffer is returned.

____________

See also:   next_buffer()


ΓòÉΓòÉΓòÉ 14.3.28. prev_buffer_key() ΓòÉΓòÉΓòÉ

prev_buffer_key()   PEL

Purpose:  To make the previous buffer current, as suitable for key assignment.

____________

Syntax:   prev_buffer_key()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.29. prev_buffer_mask() ΓòÉΓòÉΓòÉ

prev_buffer_mask()   PEL

Purpose:  To make the previous buffer that matches the current window's buffer
mask the current buffer.

____________

Syntax:   prev_buffer_mask()

____________

Arguments:  none

Description: This function differs from prev_buffer_key() in that it will
insure that the previous buffer honors the buffer mask of the current window.
If a buffer mask has not been set for the current window, this function will
operate identically to prev_buffer_key().

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.3.30. print_buffer() ΓòÉΓòÉΓòÉ

print_buffer()   Primitive

Purpose: Immediately prints the current buffer

____________

Syntax: void print_buffer( [short draft_mode] )

____________

Description: The print_buffer() function prints a marked block of text, or the
entire active file buffer if no block is marked, to the stdprn device.  Tabs
are expanded, before printing, in accordance with the current setting of the
buffer_tabs editor variable.

____________

Value returned: If a printer error occurs the executing macro is terminated.
There is therefore no point in testing the return value of print_buffer().


ΓòÉΓòÉΓòÉ 14.3.31. read_buffer() ΓòÉΓòÉΓòÉ

read_buffer()   Primitive

Purpose: read a portion of the buffer into a string.

____________

Syntax: str read_buffer([int len])

____________

Description: The read_buffer() function creates a string from the text in the
current line of the current buffer. If the len argument is omitted the text
from the cursor position to the end of the line is read.  If the len argument
is supplied, it specifies the number of characters to be read.  Positive values
for len read the characters at and following the cursor position while negative
numbers read characters preceding the cursor.  Under no conditions are
characters beyond the beginning or the end of the current line read into the
string. The end-of-line sequence will not be copied into the string.

____________

Value returned: If the cursor is located beyond the last character of the line
when this function is called an empty string is returned.  Otherwise, the
resulting string is returned.


ΓòÉΓòÉΓòÉ 14.3.32. read_file() ΓòÉΓòÉΓòÉ

read_file()   Primitive

Purpose: Read a file into the current position of current buffer.

____________

Syntax: int read_file(str file)

____________

Description: The read_file() function opens the file described by the file
argument and reads the contents into the currently active buffer at the current
cursor location.

The file argument contains a filename and, optionally, a path element including
drive specifier.  If file contains no path element the default drive and
directory are assumed.

When read_file() is completed the cursor is positioned at the end of the text
that was read.

The editor treats this as a single operation.  You may therefore obtain the
condition existing before the call to read_file() with a single undo command.

____________

Value returned: The value returned by read_file() on successful completion is
the number of bytes read into the buffer.


ΓòÉΓòÉΓòÉ 14.3.33. read_file_key() ΓòÉΓòÉΓòÉ

read_file_key()   PEL

Purpose: Enhanced function to insert file.

____________

Syntax: void read_file_key()

____________

Description: Like the read_file() function, read_file_key() prompts for a
filename and then reads that file into the buffer at the current position.  In
addition, It provides some assistance in selecting the file for reading:  It
has a history mechanism that displays the names of files previously selected
when up or down arrows are pressed.  It also will display a list of files
matching a specified pattern when  is pressed (rather than  ).  A file may then
be selected from the list.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.34. tabs() ΓòÉΓòÉΓòÉ

tabs()   PEL

Purpose: Allows defining tab stops interactively.

____________

Syntax: void tabs()

____________

Description: The tabs() function prompts the user for a new string value to be
assigned to the buffer_tabs variable.  The old value of buffer_tabs is
presented to the user for editing.

A short name has been assigned to this function to facilitate its execution
from the keyboard.  This is done through execute_function(), which is normally
assigned to a key.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.3.35. toggle_buffer_eol() ΓòÉΓòÉΓòÉ

toggle_buffer_eol()   PEL

Purpose: Convert the current buffer from DOS to UNIX, or UNIX to DOS end of
line characters.

____________

Syntax:  void toggle_buffer_eol([int unix])

____________

Description: If the optional parameter is not supplied, this function converts
the current buffer's newline sequence from the DOS standard to the UNIX
standard, or vice versa by closing and then reopening the file. If the
parameter is 0, the current file will be reopened using the DOS standard
newline sequence. If it is not 0, it will be reopened with the UNIX standard
newline sequence. This will not affect any other existing or future buffers.
You will need to call this function if your default_buffer_eol_string was not
correct when the file was opened.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  dos_edit(), unix_edit(), edit_unix_file_key(), toggle_unix()


ΓòÉΓòÉΓòÉ 14.3.36. toggle_buffer_flags() ΓòÉΓòÉΓòÉ

toggle_buffer_flags()   PEL

Purpose:  Changes the value of the buffer_flags variable.

____________

Syntax:   int toggle_buffer_flags(long mask, [long value])

____________

Arguments:

o mask - buffer_flags bit to toggle
o on - forced direction of toggle

Description: toggle_buffer_flags() changes the state of the bit in buffer_flags
specified by the mask argument.  If the optional argument, value, is supplied,
the bit changes to that value.  Otherwise the state of the bit toggles.

____________

Value returned:  TRUE  -  mask bit of status_bar_flags was turned on
FALSE -  the bit was turned off

See also: buffer_flags


ΓòÉΓòÉΓòÉ 14.3.37. toggle_unix() ΓòÉΓòÉΓòÉ

toggle_unix()   PEL

Purpose: Toggles the editor between using DOS and UNIX end of line characters
when loading buffers.

____________

Syntax:  void toggle_unix(int on)

____________

Description: This function toggles the editor's default newline sequence
between the DOS and UNIX standards if the optional parameter is not supplied.
If the parameter is 0, the default_buffer_eol_string is set to the DOS
standard. If the parameter is not 0, it is set to the UNIX standard.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  dos_edit(), unix_edit(), edit_unix_file_key(), toggle_buffer_eol()


ΓòÉΓòÉΓòÉ 14.3.38. transfer() ΓòÉΓòÉΓòÉ

transfer()   Primitive

Purpose: Transfer text to the current buffer from another buffer.

____________

Syntax: int transfer(bufid s_buf, int al, int bl [, int cl, int dl]) int cl,
int dl])

____________

Description: The transfer() function copies a block from the buffer indicated
by the s_buff argument into the currently active buffer at the cursor position.

The block of text to be copied may be specified in either of two ways.
Depending on the method selected, either two or four additional arguments are
required to define the block.

If the block of text to transfer has been enclosed within bookmarks, you need
only specify the number of those bookmarks.  These bookmarks are specified in
the al and bl arguments.  Alternately, you may specify the block of text by
line and column numbers.

In this latter case, you must give the beginning line and then the beginning
column in al and bl respectively.  These two coordinates are followed by the
ending line in the cl argument and finally the ending column in dl.  The ending
line and column define the last character which is to be copied.

If using the line and column method of defining the block to transfer, keep in
mind that line and column numbering begins with 1.

____________

Value returned: The transfer() function returns the number of characters
copied, upon successful completion. Upon error, a zero value is returned and a
message indicating the source of the error is displayed.  A block is never zero
characters.


ΓòÉΓòÉΓòÉ 14.3.39. unix_edit() ΓòÉΓòÉΓòÉ

unix_edit()   PEL

Purpose: Switch editor into UNIX newline mode.

____________

Syntax:  void unix_edit([int convertCurrent])

____________

Description: This function changes the editor's default newline sequence to the
UNIX newline sequence. This will affect all subsequent files that are opened.
If the optional parameter changeCurrent is supplied and not zero, the current
buffer will be closed and reopened to allow the changes to take affect.  You
may need to call this function if your default_buffer_eol_string is not set for
UNIX files and you want to load a UNIX file.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  dos_edit(), edit_unix_file_key(), toggle_unix(), toggle_buffer_eol()


ΓòÉΓòÉΓòÉ 14.3.40. write_all_buffers() ΓòÉΓòÉΓòÉ

write_all_buffers()   PEL

Purpose: Save the edits in modified buffers to their disk files.

____________

Syntax: int write_all_buffers()

____________

Description: The write_all_buffers() function attempts to save all buffers
containing unsaved edits to their corresponding files.

Buffers whose buffer_flags variable indicates they are not writable will not be
saved.  If a disk- write error occurs in the course of this function, the
editor will continue to attempt to save the remaining buffers after error
recovery.

____________

Value returned: No useful value is returned by this function.

____________

See also:   buffers_modified(), buffer_flags.


ΓòÉΓòÉΓòÉ 14.3.41. write_buffer() ΓòÉΓòÉΓòÉ

write_buffer()   Primitive

Purpose: Writes the contents of the current buffer to disk.

____________

Syntax: int write_buffer([str filename])

____________

Description: The write_buffer() function writes the contents of the currently
active edit buffer to a file.  The file to which the buffer is written is named
by the filename argument.  This argument may include a complete path element
including drive.  If the filename argument is omitted, the buffer is written to
the file indicated by its buffer_filename variable.  However, supplying a
filename argument does not change the name of the buffer or the buffer's
default output filename.

No check is made to determine if the buffer has actually been modified.

____________

Value returned: The value returned by write_buffer() is the number of bytes
written on successful completion.

If the buffer_flags variable indicates that writing the file is not allowed or
if a write-error occurs this function returns a zero value.  A message
indicating the source of the error is then displayed.


ΓòÉΓòÉΓòÉ 14.3.42. write_buffer_key() ΓòÉΓòÉΓòÉ

write_buffer_key()   PEL

Purpose:  Saves a buffer if it is modified.

____________

Syntax:   int write_buffer_key()

____________

Arguments: none.

Description: The write_buffer_key() function writes the current byffer to disk
if it has been modified.  If it has not been modified, no action is taken.

____________

Value returned: Number of bytes written.


ΓòÉΓòÉΓòÉ 14.4. Dynamic Data Exchange ΓòÉΓòÉΓòÉ

add_dde_server_topic()
          Associates a topic with a particular server.
create_dde_server()
          Creates a dynamic data exchange (DDE) server
dde_callback_action()
          Returns action that caused a DDE callback function call.
dde_callback_data()
          returns data of DDE conversation
dde_callback_item()
          Returns topic of DDE conversation
dde_callback_topic()
          returns topic of DDE conversation
delete_dde_server()
          Deletes a dynamic data exchange (DDE) server
delete_dde_topic()
          Deletes a dynamic data exchange (DDE) topic
get_workframe_error_info()
          Retrieve error information from IBM Workframe
initialize_dde()
          To initialize DDE communications with the stub executeable.
remove_dde_server_topic()
          Removes a topic from a server.
wf_goto_next_error()
          Step through the list of workframe errors.
wf_goto_prev_error()
          Step through the list of workframe errors.


ΓòÉΓòÉΓòÉ 14.4.1. add_dde_server_topic() ΓòÉΓòÉΓòÉ

add_dde_server_topic()   Primitive

Purpose: Associates a topic with a particular server.

____________

Syntax: long add_dde_server_topic(long serverid, long topicid)

____________

Description: The add_dde_server_topic() function associates a topic with a
server.  The server can then accept requests from clients with the topic id
specified in the function call.  The topic id should not be deleted while it is
in use by any server.  The remove_dde_server_topic() call should be used to
remove the topic from the server before deleting it.  The serverid argument
contains the id of the server the topic is to be associated with.  The serverid
must have been returned from a call to create_dde_server().

____________

Value returned: TRUE if successful, FALSE otherwise.


ΓòÉΓòÉΓòÉ 14.4.2. create_dde_server() ΓòÉΓòÉΓòÉ

create_dde_server()   Primitive

Purpose: Creates a dynamic data exchange (DDE) server

____________

Syntax: serverid create_dde_server(string servername, macroid callback)

____________

Description: The create_dde_server() function registers a new dynamic data
exchange server with the editor.  After create_dde_server() is called the
editor will then respond to requests from DDE clients.  The servername argument
is the name that the server will be registered as.  Any clients wishing to
communicate with this server must specify the exact same string as servername
in order for the connection to be successful.  The callback argument is the
macro id of the function to call to notify the user of significant DDE events.

____________

Value returned: The create_dde_server() function returns the id of the newly
created server if successful, otherwise 0 will be returned.


ΓòÉΓòÉΓòÉ 14.4.3. dde_callback_action() ΓòÉΓòÉΓòÉ

dde_callback_action   Primitive

Purpose:  Returns action that caused a DDE callback function call.

____________

Syntax:   long dde_callback_action(long serverid)

____________

Arguments:

o serverid - id of the server

Description: This function returns the action code that caused a DDE callback
function call.  This function will always return the last DDE action code that
was generated by the system. The return value of this function may only be
modified by the system.


ΓòÉΓòÉΓòÉ 14.4.4. dde_callback_data() ΓòÉΓòÉΓòÉ

dde_callback_data   Primitive

Purpose:  returns data of DDE conversation

____________

Syntax:   str dde_callback_action(long serverid)

____________

Arguments:

o serverid - id of the server

Description: When the editor receives a DDE message from the system this
function will return the data for the DDE conversation.  The editor can only
accept DDE data in string format.  If a DDE client or server sends data in any
other format it will not be recognized by the editor.  The return value of this
function may only be modified by the system.


ΓòÉΓòÉΓòÉ 14.4.5. dde_callback_item() ΓòÉΓòÉΓòÉ

dde_callback_item   Primitive

Purpose:  Returns topic of DDE conversation

____________

Syntax:   long dde_callback_action(long serverid)

____________

Arguments:

o serverid - id of the server

Description: When the editor receives a DDE message from the system this
function will return the item of the DDE conversation.  The item will always be
an item that was previously associated with a topic via the add_dde_item()
function.  The return value of this function may only be modified by the
system.


ΓòÉΓòÉΓòÉ 14.4.6. dde_callback_topic() ΓòÉΓòÉΓòÉ

dde_callback_topic   Primitive

Purpose:  returns topic of DDE conversation

____________

Syntax:   str dde_callback_action(long serverid)

____________

Arguments:

o serverid - id of the server

Description: The dde_callback_topic function returns the topic of the DDE
conversation that caused the DDE callback function to be called. Only topics
that were previously registered are recognized as valid topic strings.  The
return value of this function may only be modified by the system.


ΓòÉΓòÉΓòÉ 14.4.7. delete_dde_server() ΓòÉΓòÉΓòÉ

delete_dde_server()   Primitive

Purpose: Deletes a dynamic data exchange (DDE) server

____________

Syntax: void delete_dde_server(long serverid)

____________

Description: The delete_dde_server() function deletes the DDE server specified
in the serverid argument.  The serverid argument must have been returned from
the create_dde_server function call.  After delete_dde_server() is called the
editor will no longer accept connections from DDE clients for the serverid DDE
server.

____________

Value returned: The delete_dde_server() function does not return a value.


ΓòÉΓòÉΓòÉ 14.4.8. delete_dde_topic() ΓòÉΓòÉΓòÉ

delete_dde_topic()   Primitive

Purpose: Deletes a dynamic data exchange (DDE) topic

____________

Syntax: void delete_dde_topic(long topicid)

____________

Description: The delete_dde_topic() function deletes the memory associated with
a DDE topic.  The DDE topic should not be attached to any server when it is
deleted. Use the remove_dde_server_topic() function for each server that is
using the topic before calling delete_dde_topic().  The topicid argument
contains the id of a topic returned from the create_dde_topic() function.

____________

Value returned: The delete_dde_topic() function does not return a value.


ΓòÉΓòÉΓòÉ 14.4.9. get_workframe_error_info() ΓòÉΓòÉΓòÉ

get_workframe_error_info()   Primitive

Purpose: Retrieve error information from IBM Workframe

____________

Syntax: void get_workframe_error_info( long serverid, string buffername, long
magicid )

____________

Description: The get_workframe_error_info() function retrieves error
information from the IBM Workframe development environment.

The serverid argument is the DDE server name to send the information from.
This must be a value returned from the create_dde_server()  function call.

The buffername argument is the buffer name that errors are requested for.

The magicid argument is the position in the Workframe compiler list box that
contains the error string.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.4.10. initialize_dde() ΓòÉΓòÉΓòÉ

initialize_dde()   PEL

Purpose:  To initialize DDE communications with the stub executeable.

____________

Syntax:   initialize_dde()

____________

Arguments:  none

Description: This function is, by default, called from local_setup().  You
would normally not need to call this yourself, but it does serve as a good
example of initializing DDE communictions.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.4.11. remove_dde_server_topic() ΓòÉΓòÉΓòÉ

remove_dde_server_topic()   Primitive

Purpose: Removes a topic from a server.

____________

Syntax: void remove_dde_server_topic(long serverid, String topic)

____________

Description: The remove_dde_server_topic() function removes a particular topic
from a server.  The server will no longer respond to request for the particular
topic.  The serverid argument contains the server from which the topic will be
removed.

The topic argument contains the string name of the topic to delete.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.4.12. wf_goto_next_error() ΓòÉΓòÉΓòÉ

wf_goto_next_error()   PEL

Purpose:  Step through the list of workframe errors.

____________

Syntax:   void wf_goto_next_error()

____________

Arguments: none.

Description: The wf_goto_next_error() function moves the cursor to the position
specified by the next error in the list of errors generated by Workframe.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.4.13. wf_goto_prev_error() ΓòÉΓòÉΓòÉ

wf_goto_prev_error()   PEL

Purpose:  Step through the list of workframe errors.

____________

Syntax:   void wf_goto_prev_error()

____________

Arguments: none.

Description: The wf_goto_prev_error() function moves the cursor to the position
specified by the previous error in the list of errors generated by Workframe.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.5. Dialog Windows ΓòÉΓòÉΓòÉ

add_dialog_item()
          Adds a dialog control to a dialog box.
add_item_to_list()
          To add an item to a list dialog.
begin_dialog()
          Displays a dialog box.
create_dialog()
          Creates a modal dialog box from a resource file.
create_dialog_template()
          Creates a blank modal dialog box.
create_list_dialog()
          To create a standard list dialog.
create_mdialog()
          Creates a modeless dialog box from a resource file.
create_mdialog_template()
          Creates a blank modeless dialog box.
create_selection_dialog()
          To create a dialog which prompts the user with a list of selections.
delete_dialog()
           Removes a dialog box from memory.
delete_list_dialog()
          To delete a list dialog window
dialog_history()
          Set a up a history for a dialog box.
dialog_list()
          Displays the list of list dialogs.
first_dialog()
          To get the handle of the dialog window first in the internal list.
goto_next_error()
          Move cursor to position of next compile error.
next_dialog()
          To get the handle of the dialog window next in the internal list.
query_dialog_item()
          Queries various information about a dialog control.
query_dialog_window()
          To query different dialog window attributes.
select_menuitem()
          Selects a particular menu item.
set_dialog_focus()
          Sets focus to a control contained in a dialog box
set_dialog_item()
          Sets various attributes of a given dialog control.
set_dialog_window()
          To set different dialog window attributes.


ΓòÉΓòÉΓòÉ 14.5.1. add_dialog_item() ΓòÉΓòÉΓòÉ

add_dialog_item()   Primitive

Purpose: Adds a dialog control to a dialog box.

____________

Syntax: long add_dialog_item ( long  dlgid, short  index, short  style,[string
label,[short  x0, short  y0, short  width, short  height]] )

____________

Description: The add_dialog_item() function adds a dialog control to a dialog
box. The dialog box can be created with any of the dialog box creation
functions.

The dlgid argument contains the dialog box window that the control is added to.

The index argument contains the id of the dialog control.  The index is used to
identify the control in all other dialog control functions.

The style argument contains the type of control to create. The style argument
can be one of the following:

DCTRL_DEFAULT_PUSH_BUTTON  - default push button
DCTRL_PUSH_BUTTON          - normal push button
DCTRL_RADIO_BUTTON         - radio button
DCTRL_CHECK_BOX            - normal check box
DCTRL_TRISTATE             - 3 state check box
DCTRL_EDIT                 - edit box
DCTRL_EDIT_KEY             - same as DCTRL_EDIT
DCTRL_STATIC_TEXT          - static text
DCTRL_GROUP_BOX            - group box
DCTRL_LIST_BOX             - list box
DCTRL_COMBO_BOX            - combo box
DCTRL_NOTEBOOK             - notebook
DCTRL_MULTI_LIST_BOX       - multiple select list box

The label argument contains the text of the control.  The label argument
affects controls in the following way:

DCTRL_DEFAULT_PUSH_BUTTON  - push button text
DCTRL_PUSH_BUTTON          - push button text
DCTRL_RADIO_BUTTON         - radio button text
DCTRL_CHECK_BOX            - check box text
DCTRL_TRISTATE             - check box text
DCTRL_EDIT                 - no effect
DCTRL_EDIT_KEY             - no effect
DCTRL_STATIC_TEXT          - text of control
DCTRL_GROUP_BOX            - group box title
DCTRL_LIST_BOX             - no effect
DCTRL_COMBO_BOX            - no effect
DCTRL_NOTEBOOK             - no effect
DCTRL_MULTI_LIST_BOX       - no effect

The x0 argument contains the initial x position in pixels for the dialog box
control.  The lower left corner of the dialog box is the origin.  If the x0
argument is specified y0, width, and height arguments must also be specified.

The y0 argument contains the initial y position for the dialog box control.

The width argument contains the initial width of the dialog box control.

The height argument contains the initial height of the dialog box control.

____________

Value returned: This function returns the dialog box control id.


ΓòÉΓòÉΓòÉ 14.5.2. add_item_to_list() ΓòÉΓòÉΓòÉ

add_item_to_list()   PEL

Purpose:  To add an item to a list dialog.

____________

Syntax:   add_item_to_list(int dlgid, str data, str filename, int line, int
col, [int hlen] )

____________

Arguments:

o dlgid   - dialog box to add item to
o data   - data to put in the list box
o filename - filename to load when item is selected
o line   - line in file to goto when item is selected
o col    - column in file to goto when item is selected
o hlen   - highlight length.

Description: This function adds an item to a list dialog, and stores the
information necessary to perform the Goto, Next and Prev functions of the
dialog.  If hlen is zero no text is highlighted, if it is -1 the whole line is
highlighted, if it is -2 all characters from col to the end-of-line are
selected, otherwise hlen characters are highlighted starting at col.

See also:  create_list_dialog(), valid_list_dialog(), delete_list_dialog()

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.5.3. begin_dialog() ΓòÉΓòÉΓòÉ

begin_dialog()   Primitive

Purpose: Displays a dialog box.

____________

Syntax: void begin_dialog(long dlgid, [bool auto_delete])

____________

Arguments:

dlgd - contains the dialog window to display.  This argument must be a value
returned from a create_[m]dialog() function.

auto_delete - setting this flag to TRUE tells the dialog to delete itself when
it is closed. Because this is an optional argument, it is FALSE by default.

____________

Description: The begin_dialog() function displays a dialog box for user input.
For modal dialog boxes this function will not return until the dialog box is
closed.  This function returns immediately for modeless dialog boxes.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.5.4. create_dialog() ΓòÉΓòÉΓòÉ

create_dialog()   Primitive

Purpose: Creates a modal dialog box from a resource file.

____________

Syntax: long create_dialog( macroid callback_id, long parent, long resource_id,
[string  resource_file, [string  label]] )

____________

Description: The create_dialog() function creates a modal dialog box from a
resource file.  Dialog boxes created with this function must reside in a
resource dll.  See the RESOURCE DLL section for more information on creating
and using resource dll's.

The callback_id argument contains the macro id of the function that is called
whenever an important dialog event occurs.  See the section on DIALOG EVENTS
for a list of events that could occur.

The parent argument contains the parent of the dialog box. The following are
valid values for the parent argument:


value dialog's parent
----- ---------------
 -1  no parent
 0  main editor window
other another dialog box id

The resource_id argument contains the resource id of the dialog box. The
resource_id must be in either the default resource dll or the resource dll
specified by the resource_file parameter.

The resource_file argument contains the resource dll that holds the dialog box
resource.  This file must be in a directory contained in your LIBPATH
environment variable for OS/2 or your PATH environment variable for Windows.
If this argument is not specified or is an empty string then the default
resource dll will be used.  On startup all resources are retrieved from the
executable file unless a call to the use_resource_file() function is made.

The label argument contains an optional title for the dialog box.  The label is
displayed on the dialog box caption bar.

____________

Value returned: The create_dialog() function returns the dialog id of the newly
created dialog box or 0 if the call failed.


ΓòÉΓòÉΓòÉ 14.5.5. create_dialog_template() ΓòÉΓòÉΓòÉ

create_dialog_template()   Primitive

Purpose: Creates a blank modal dialog box.

____________

Syntax: long create_dialog_template(  macroid  callback_id, long  parent,
string label,[short x0,short y0, short width, short height] )

____________

Description: The create_dialog_template() function creates a blank modal dialog
box that is used for creating dialog boxes without resource files. After the
create_dialog_template() function is called then the add_dialog_item() function
can be used to add controls to the dialog box.

The callback_id argument contains the macro id of the function that is called
whenever an important dialog event occurs.  See the section on DIALOG EVENTS
for a list of events that could occur.

The parent argument contains the parent of the dialog box. The following are
valid values for the parent argument:


value dialog's parent
----- ---------------
 -1  no parent
 0  main editor window
   other another dialog box id

The label argument contains the title for the dialog box.  The label is
displayed on the dialog box caption bar.

The x0 argument contains the initial x position for the dialog box. The lower
left corner of the editor is the origin.  If the x0 argument is specified y0,
width, and height arguments must also be specified.

The y0 argument contains the initial y position for the dialog box.

The width argument contains the initial width of the dialog box.

The height argument contains the initial height of the dialog box.

____________

Value returned: The create_dialog_template() function returns the dialog id of
the newly created dialog box or 0 if the call failed.


ΓòÉΓòÉΓòÉ 14.5.6. create_list_dialog() ΓòÉΓòÉΓòÉ

create_list_dialog()   PEL

Purpose:  To create a standard list dialog.

____________

Syntax:   create_list_dialog( str title, [str help_file, [funcid sub_callback]]
)

____________

Arguments:

o title - the title of the dialog window
o help_file - the help file to attach to the dialog window
o sub_callback - substitute callback function

Description: This function creates a standard list dialog such as the ones used
by the Bookmark List, Find All Lists, and Dialog Lists. The functionality of
the Goto, Prev, Next, Close, and Help buttons are handled automatically. To
customize the dialog, you may provide an optional substitute callback function
that will change or add to the already existing functionality.  The default
callback function is dlg_list_callback(), which you may call from within your
own callback to handle any messages you do not wish to process. The Find All
list extends the standard list dialog in this way in order to add Stop button.

See also:  add_item_to_list(), valid_list_dialog(), delete_list_dialog()

____________

Value returned: This function returns the dialog id of the list dialog.


ΓòÉΓòÉΓòÉ 14.5.7. create_mdialog() ΓòÉΓòÉΓòÉ

create_mdialog()   Primitive

Purpose: Creates a modeless dialog box from a resource file.

____________

Syntax: long create_mdialog( macroid callback_id, long parent, long
resource_id, [string  resource_file, [string  label]] )

____________

Description: The create_mdialog() function creates a modeless dialog box from a
resource file.  Dialog boxes created with this function must reside in a
resource dll.  See the RESOURCE DLL section for more information on creating
and using resource dll's.

The callback_id argument contains the macro id of the function that is called
whenever an important dialog event occurs.  See the section on DIALOG EVENTS
for a list of events that could occur.

The parent argument contains the parent of the dialog box. The following are
valid values for the parent argument:


value dialog's parent
----- ---------------
 -1  no parent
 0  main editor window
   other another dialog box id

The resource_id argument contains the resource id of the dialog box. The
resource_id must be in either the default resource dll or the resource dll
specified by the resource_file parameter.

The resource_file argument contains the resource dll that holds the dialog box
resource.  This file must be in a directory contained in your LIBPATH
environment variable for OS/2 or your PATH environment variable for Windows.
If this argument is not specified or is an empty string then the default
resource dll will be used.  On startup all resources are retrieved from the
executable file unless a call to the use_resource_file() function is made.

The label argument contains an optional title for the dialog box.  The label is
displayed on the dialog box caption bar.

____________

Value returned: The create_mdialog() function returns the dialog id of the
newly created dialog box or 0 if the call failed.


ΓòÉΓòÉΓòÉ 14.5.8. create_mdialog_template() ΓòÉΓòÉΓòÉ

create_mdialog_template()   Primitive

Purpose: Creates a blank modeless dialog box.

____________

Syntax: long create_mdialog_template( macroid  callback_id, long parent, string
label, [short   x0, short   y0, short width, short   height] )

____________

Description: The create_mdialog_template() function creates a blank modeless
dialog box that is used for creating dialog boxes without resource files. After
the create_mdialog_template() function is called then the add_dialog_item()
function can be used to add controls to the dialog box.

The callback_id argument contains the macro id of the function that is called
whenever an important dialog event occurs.  See the section on DIALOG EVENTS
for a list of events that could occur.

The parent argument contains the parent of the dialog box. The following are
valid values for the parent argument:


value dialog's parent
----- ---------------
 -1  no parent
 0  main editor window
   other another dialog box id

The label argument contains the title for the dialog box.  The label is
displayed on the dialog box caption bar.

The x0 argument contains the initial x position for the dialog box. The lower
left corner of the editor is the origin.  If the x0 argument is specified y0,
width, and height arguments must also be specified.

The y0 argument contains the initial y position for the dialog box.

The width argument contains the initial width of the dialog box.

The height argument contains the initial height of the dialog box.

____________

Value returned: The create_mdialog_template() function returns the dialog id of
the newly created dialog box or 0 if the call failed.


ΓòÉΓòÉΓòÉ 14.5.9. create_selection_dialog() ΓòÉΓòÉΓòÉ

create_selection_dialog()   PEL

Purpose:  To create a dialog which prompts the user with a list of selections.

____________

Syntax:   create_selection_dialog( str title, int width, array list, [int
parent] )

____________

Arguments:

o title - the title of the dialog
o width - the width of the dialog, in list box characters
o list - an array of selections to enter into the list
o parent - the parent id of the dialog, 0 for editor window

Description: This function creates a dialog which provides the user with a list
of selections to choose from, one of the most convenient forms of input in the
editor. In order to prompt the user to select from a list of strings, call this
function to create the dialog, call begin_dialog() to display the dialog, and
then the variable new_response will contain the item selected by the user, or
"" if cancel was selected.

____________

Value returned:  the id of the dialog window created


ΓòÉΓòÉΓòÉ 14.5.10. delete_dialog() ΓòÉΓòÉΓòÉ

delete_dialog()   Primitive

Purpose:  Removes a dialog box from memory.

____________

Syntax:  void delete_dialog(long dlgid)

____________

Description: The delete_dialog() function deletes a dialog window from memory.
The dialog window will be invalid after this call is made.  This function
should be called whenever you no longer need a dialog box.

The dlgid argument contains the dialog window to delete.

____________

Value returned: The delete_dialog() function does not return any useful value.


ΓòÉΓòÉΓòÉ 14.5.11. delete_list_dialog() ΓòÉΓòÉΓòÉ

delete_list_dialog()   PEL

Purpose:  To delete a list dialog window

____________

Syntax:   delete_list_dialog( int dlgid )

____________

Arguments:

o dlgid - the list dialog to delete

Description: This function deletes the specified list dialog and the
information associated with that dialog.

See also:  create_list_dialog(), add_item_to_list(), valid_list_dialog()

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.5.12. dialog_history() ΓòÉΓòÉΓòÉ

dialog_history()   PEL

Purpose:  Set a up a history for a dialog box.

____________

Syntax:   void dialog_history( long dlgHand, short dlgId, str histName )

____________

Arguments:

o dlgHand - Handle of the dialog
o dlgId - Id of the control which will have the associated history
o histName - string name of the history list

Description: The dialog_history() function associates a history list to the
specified control in the given dialog.  The user may then use arrow keys and
the tab key to cycle through the list or expand the current entry.

____________

Value returned: None


ΓòÉΓòÉΓòÉ 14.5.13. dialog_list() ΓòÉΓòÉΓòÉ

dialog_list()   PEL

Purpose:  Displays the list of list dialogs.

____________

Syntax:   dialog_list()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.5.14. first_dialog() ΓòÉΓòÉΓòÉ

first_dialog()   Primitive

Purpose: To get the handle of the dialog window first in the internal list.

____________

Syntax: first_dialog()

____________

Description: This function is used to get the handle of the dialog window first
in the internal list of dialogs.  Call this function to get the first handle,
and then next_dialog() to get the next consecutive dialogs.

____________

Value returned:  The handle of the dialog window first in the internal list, or
NULL if their are no dialogs in the list.


ΓòÉΓòÉΓòÉ 14.5.15. goto_next_error() ΓòÉΓòÉΓòÉ

goto_next_error()   PEL

Purpose: Move cursor to position of next compile error.

____________

Syntax:  void goto_next_error()

____________

Description: The goto_next_error() function allows the user to move
sequentially in the source code from one compile error to the next.

On the first call to goto_next_error(), after a compile, the function
determines from the name of the current buffer the name of the file in which
error messages have been captured.  It then locates and displays the position
in the source code of the first error listed in that file.  The associated
error message is displayed in the dialog window.

On subsequent calls to goto_next_error(), the next message in the error listing
file is read, the cursor is positioned at the proper place in the appropriate
file, and again the error message is displayed in the dialog window.

If there are no known rules for parsing the error messages associated with the
current buffer, this function cannot succeed.  A message to that effect is then
displayed. Several sets of error parsing rules which may be associated with
filename extensions. This may be done using the add_compiler() function.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.5.16. next_dialog() ΓòÉΓòÉΓòÉ

next_dialog()   Primitive

Purpose: To get the handle of the dialog window next in the internal list.

____________

Syntax: next_dialog()

____________

Description: This function is used to get the handle of the dialog window next
in the internal list of dialogs.  Call first_dialog() to get the dialog first
in the list, and then next_dialog() to step through the list of dialogs.

____________

Value returned:  The handle of the dialog window next in the internal list, or
NULL if there are no more dialogs in the list.


ΓòÉΓòÉΓòÉ 14.5.17. query_dialog_item() ΓòÉΓòÉΓòÉ

query_dialog_item()   Primitive

Purpose: Queries various information about a dialog control.

____________

Syntax: any query_dialog_item(long  dlgid, short index, short flag, [any
value] )

____________

Description: The query_dialog_item() function queries various information about
a dialog control.

The dlgid argument contains the dialog id which contains the control.

The index argument contains the id of the control.

The flag argument contains the attribute of the dialog control to query.

o DAC_CHECK
o DAC_COUNT_ITEMS
o DAC_COUNT_SELECTED
o DAC_DISABLE
o DAC_ENABLE
o DAC_FIRST_INDEX
o DAC_FIRST_ITEM
o DAC_GET_INDEX_ITEM
o DAC_GRAY_CHECK
o DAC_HIDE
o DAC_NEXT_INDEX
o DAC_NEXT_ITEM
o DAC_SELECT_INDEX
o DAC_SELECT_ITEM
o DAC_SHOW
o DAC_TEXT
o DAC_UNCHECK
o DAC_VS_QUERY_ITEM
o DAC_VS_QUERY_METRICS
o DAC_VS_QUERY_SELECTED
o DAC_VS_SET_ITEM
o DAC_VS_SET_METRICS

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.5.18. query_dialog_window() ΓòÉΓòÉΓòÉ

query_dialog_window()   Primitive

Purpose: To query different dialog window attributes.

____________

Syntax: any query_dialog_window(  long  dlghand, short flag, [any  value, any
value2]] )

____________

Description: This function allows you to query the following dialog window
attributes:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFlag            ΓöéReturn value                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_TITLE:      ΓöéTitle of the dialog window    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_POSITION:   ΓöéPosition of the window on the Γöé
Γöé                Γöéscreen in pixels.             Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_SIZE:       ΓöéSize of the dialog window in  Γöé
Γöé                Γöépixels.                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_HIDE:       ΓöéTRUE if hidden, FALSE if      Γöé
Γöé                Γöévisible                       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_SHOW:       ΓöéTRUE if visible, FALSE if     Γöé
Γöé                Γöéhidden                        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_ICONIZED    ΓöéTRUE if the dialog is         Γöé
Γöé                Γöéiconized, FALSE if not        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéDWC_ZOOMED      ΓöéTRUE if dialog is zoomed,     Γöé
Γöé                ΓöéFALSE if not                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Value returned: Returns the value of the attribute specified.


ΓòÉΓòÉΓòÉ 14.5.19. select_menuitem() ΓòÉΓòÉΓòÉ

select_menuitem()   Primitive

Purpose: Selects a particular menu item.

____________

Syntax: void select_menuitem()

____________

Description: The select_menuitem() function selects a menu item from the main
application menu.  The menu accelerators are used to select the particular menu
item based on the current_key() variable. For example, if current_key() was 'F'
and the select_menuitem() function was called the menu item with an 'F' as its
accelerator key would be selected. If currentKey doesn't match any menu
accelerator then the first menu item is selected.

The select_menuitem() function is especially useful in keymaps to map
<Alt-....> combinations to select menu items.

____________

Value returned: The select_menuitem() function does not return a value.


ΓòÉΓòÉΓòÉ 14.5.20. set_dialog_focus() ΓòÉΓòÉΓòÉ

set_dialog_focus()   Primitive

Purpose: Sets focus to a control contained in a dialog box

____________

Syntax: void set_dialog_focus(long dlgid, short index)

____________

Description: The set_dialog_focus() function gives focus to the specified
control contained in a dialog box.  The control which contains focus in a
dialog box receives all keyboard input with the exception of accelerator keys.

The dlgid argument contains the id of the dialog box which contains the
control.

The index argument contains the control id of the control contained in the
dialog box.  The index argument is either the id specified in the resource file
if the dialog box was created from a resource dll or the id used in the
add_dialog_item() function call.

____________

Value returned: No value is returned.


ΓòÉΓòÉΓòÉ 14.5.21. set_dialog_item() ΓòÉΓòÉΓòÉ

set_dialog_item()   Primitive

Purpose: Sets various attributes of a given dialog control.

____________

Syntax: long set_dialog_item(long  dlgid,  short index, short flag, [any
value1, ...[any value7]])

____________

Description: The set_dialog_item() function sets various attributes of a given
dialog control.

The dlgid argument is the dialog box that the control is on.

The index argument contains the id of the dialog control.

The flag argument contains the attribute of the dialog control to set:

Valid Controls:

o DAC_ADD_INDEX
o DAC_ADD_ITEM
o DAC_APPEND_PAGE
o DAC_CHECK
o DAC_BG_COLOR
o DAC_DELETE_INDEX
o DAC_DELETE_ITEM
o DAC_DESELECT_INDEX
o DAC_DESELECT_INDEX_RANGE
o DAC_DESELECT_ITEMADDINDEX
o DAC_DISABLE
o DAC_ENABLE
o DAC_FG_COLOR
o DAC_GRAY_CHECK
o DAC_HIDE
o DAC_INSERT_PAGE_AFTER
o DAC_INSERT_PAGE_AT_TOP
o DAC_INSERT_PAGE_BEFORE
o DAC_NO_SORT
o DAC_POSITION
o DAC_SELECT_INDEX
o DAC_SELECT_INDEX_RANGE
o DAC_SELECT_ITEM
o DAC_SETFOCUS
o DAC_SET_BACKPAGES
o DAC_SET_BINDER_TYPE
o DAC_SET_BUTTON_SIZE
o DAC_SET_MAJOR_TAB_SIZE
o DAC_SET_MINOR_TAB_SIZE
o DAC_SET_STATUS_ALIGN
o DAC_SET_TAB_ALIGN
o DAC_SET_TAB_LOCATION
o DAC_SET_TAB_TYPE
o DAC_SET_TEXT_LEN
o DAC_SHOW
o DAC_SIZE
o DAC_SORT_ASCENDING
o DAC_SORT_DESCENDING
o DAC_SPIN_DOWN
o DAC_SPIN_LIMITS
o DAC_SPIN_OVERRIDELIMITS
o DAC_SPIN_TEXTLIMIT
o DAC_SPIN_UP
o DAC_SPIN_VALUE
o DAC_TEXT
o DAC_UNCHECK
o DAC_VS_SELECT_ITEM

The optional value arguments vary depending on the flag parameter.

____________

Value returned: The return value depends of the flag argument. In all cases if
the operation failed a 0 is returned.  Otherwise, in most other cases a 1 is
returned for success.  The following flag values do not return 1 to indicate
success but some other value.

Flag successful          Return value
DAC_ADDITEM              returns to position of the newly inserted item
DAC_ADDINDEX             returns to position of the newly inserted item
DAC_APPENDPAGE           returns the page id of the page
DAC_INSERTPAGEATTOP      returns the page id of the page
DAC_INSERTPAGEBEFORE     returns the page id of the page
DAC_INSERTPAGEAFTER      returns the page id of the page


ΓòÉΓòÉΓòÉ 14.5.22. set_dialog_window() ΓòÉΓòÉΓòÉ

set_dialog_window()   Primitive

Purpose: To set different dialog window attributes.

____________

Syntax: void set_dialog_window(long dlghand, short flag, [any value, [any
value2, [any value3, [any value4]]]])

____________

Description: This function allows you to set the following dialog window
attributes:

DWC_ICONIZED:  Iconizes the dialog.
DWC_ZOOMED: Zooms the dialog.

DWC_TITLE:     Changes the title of the dialog window
           set_dialog_window(dh, DWC_TITLE, "My
Dialog")

DWC_POSITION:   Changes the position of the window on the
screen,
         specified in pixels.
           set_dialog_window(dh, DWC_POSITION,
x_position, y_position)

DWC_SIZE:     Changes the size of the dialog window, in
pixels.
           set_dialog_window(dh, DWC_SIZE,
x_dimension, y_dimension)

DWC_HIDE:     Hides the dialog(makes it no longer visible on
the screen)
           set_dialog_window(dh, DWC_HIDE)

DWC_SHOW:     Shows the dialog(makes it visible on the
screen)
           set_dialog_window(dh, DWC_SHOW)

DWC_TO_TOP:    Moves the dialog to the top of the window stack
           set_dialog_window(dh, DWC_TO_TOP)

DWC_SIZEBORDER:  Changes the border of the dialog to a
user-sizeable border
           set_dialog_window(dh, DWC_SIZEBORDER)

DWC_NORMALBORDER: Changes the border of the dialog to a normal
window border
           set_dialog_window(dh, DWC_NORMALBORDER)

DWC_STICKONTOP:   Causes a modeless dialog box to always be on top of
(above) its parent window.

____________

Value returned: Returns TRUE on success, FALSE on failure.


ΓòÉΓòÉΓòÉ 14.5.23. valid_list_dialog() ΓòÉΓòÉΓòÉ

valid_list_dialog()   Primitive

Purpose: To query whether a dialog id is a valid list dialog.

____________

Syntax: valid_list_dialog( int dlgid )

____________

Arguments:

dlgid - contains the dialog window handle to be queried.

____________

Description: The valid_list_dialog() function returns whether or not the input
parameter is a valid dialog list dialog box.

____________

Value returned:

1 (TRUE) - if dlgid is a valid list dialog box.

0 (FALSE) - if dlgid is not a valid list dialog box.

____________

See also: create_list_dialog()


ΓòÉΓòÉΓòÉ 14.6. Editor System ΓòÉΓòÉΓòÉ

The functions and variables in the Editor System category are general to the
tasks that SPE must perform.  The variables specify which directories are to be
used by the editor, which buffers and windows are presently selected and
provide information about recent activities.

The variables in this category include several that allow setting the text
attributes for various features of the editor.  While these are system wide
variables, there are several similar variables that set the attributes of
window features.  This latter group of variables may be set independently for
each window and are therefore listed in the Windowing category.  The possible
values for these attributes in both categories are discussed and listed in the
"Windowing" chapter.

The functions in this category perform services that are not specific to a
single buffer or window.  For this reason they are somewhat miscellaneous in
nature.  The services provided include everything from quitting your SPE
session to invoking nested editing processes.  Also included are functions to
update the screen and for obtaining information about the functions in use.

Among the functions listed here is autosave().  This function activates a
feature that saves buffers to disk after a predefined interval during which no
typing occurs.  You set the interval with the autosave_time variable.

Another important function is the local_setup() function.  Use this function to
modify defaults and general initialization.  This is where customizing SPE
begins.

autosave()
          Toggles the auto-save feature on or off.
backup_file()
          Makes backup copies of files, when enabled.
display_redraw()
          Redraw the entire visible screen.
display_update()
          Update the visible screen with recent changes.
done()
          Exiting the editor normally.
execute_function()
          Calls a function with a string containing its invocation.
invoke_function()
          Send a query or request to PEL interpreter.
local_setup()
          Builds in your personal preferences.
print_version()
          Shows what version of the editor is in use.
process_begin()
          Initiate a nested editing process.
process_end()
          Terminate a nested editing process.
pwd()
          Displays the current working directory
query_editwin_property()
          Allows you to view the EWC_MAXIMIZE, EWC_NORMAL and EWC_MINIMIZE
          proterties
quit()
          Exits the editor in an orderly fashion.
set_editwin_property()
          To set various properties of the main editor window.
toggle_file_backup()
          Toggles creation of backup files.
toggle_status_bar()
          Sets or toggles the status bar.
toggle_stb_flags()
          Toggles the value of the search_flags variable.
tracking_bottom
          Bottom side of the tracking rectangle.
tracking_height
          Height of tracking rectangle.
tracking_left
          Left side of tracking rectangle.
tracking_width
          Width of tracking rectangle.
update_current_view()
          To update the display of the current window.
write_and_exit()
          Save all buffers and exit the editor.


ΓòÉΓòÉΓòÉ 14.6.1. autosave() ΓòÉΓòÉΓòÉ

autosave()   PEL

Purpose: Toggles the auto-save feature on or off.

____________

Syntax:  void autosave([int atime [, int ftime]])

____________

Description: The autosave() function toggles the use of the editor's auto-save
feature.  A message is then displayed indicating if the feature has been turned
on or off.

The autosave() feature automatically saves a buffer to disk after a specified
period of keyboard inactivity.  The period of inactivity is specified in
seconds and is determined by the setting of the autosave_time variable.  The
optional time argument may be used to set autosave_time at the same time as
toggling on the autosave feature.

The ftime argument indicates the number of seconds between forced saves.  That
is, saves which occur without regard to keyboard activity.  This "forced saves"
interval may be specified when toggling on autosave(), or by setting the
autosave_force_time variable.  Either way, the interval is specified in
seconds. Calling autosave() with an argument of 0 always turns off the
auto-save feature regardless of its previous setting.  Non- zero values for
this argument always turn it on.

The buffer is not saved under the filename associated with the buffer (
buffer_filename ) since this would make it less convenient to abandon changes.
Instead, the filename under which it is saved is derived from buffer_filename
by making the third character of the extension a "!".  If the extension has
less than two characters (e.g., ".C"), the extension is filled with underscores
(e.g., ".C_!"). Thus, the auto-save file is stored in the same directory as the
buffer's filename. If this extension presents a problem, you may modify the
function library source code, found in AUTOSAVE.PEL, to assign a different
extension to auto-save files.

Files created by the auto-save function are deleted when the editor is exited
normally. If power is lost or abort() is used to terminate the edit session
these files are not deleted.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.6.2. backup_file() ΓòÉΓòÉΓòÉ

backup_file()   PEL

Purpose: Makes backup copies of files, when enabled.

____________

Syntax:  int backup_file(str fname)

____________

Description: The backup_file() function saves a backup of file named by fname
in the directory described by the backup_directory variable. If file backups
have not been enabled ( toggle_file_backup() ), no backup is made. The
extension applied to the backup file is controlled by the backup_file_ext
variable.

This function is used as part of the save process in the emulation packages.
The making of backup copies may then be toggled on and off through the
toggle_file_backup() function.

This function renames (moves) the fname file to the file in the backup
directory. This has the effect of removing the original file.  For this reason
backup_file() should only be performed if the original file will immediately be
restored by a save.  The best form for using this function is as follows:

 {if ( buffer_is_modified() )
   { backup_file( buffer_filename )
   write_buffer()
   }
 }

____________

Value returned: This function returns FALSE ( 0 ) if fname cannot be found.  It
otherwise returns TRUE ( 1 ).

____________

See also:  toggle_file_backup()


ΓòÉΓòÉΓòÉ 14.6.3. display_redraw() ΓòÉΓòÉΓòÉ

display_redraw()   Primitive

Purpose: Redraw the entire visible screen.

____________

Syntax:  void display_redraw()

____________

Description: The display_redraw() function re-draws the display screen
including the contents of all visible windows.  This function is useful when
you have run a program that fails to properly restore the screen.

____________

Value returned: No useful value is returned by the display_redraw() function.

____________

See also:  display_update()


ΓòÉΓòÉΓòÉ 14.6.4. display_update() ΓòÉΓòÉΓòÉ

display_update()   Primitive

Purpose: Update the visible screen with recent changes.

____________

Syntax:  void display_update()

____________

Description: The display_update() function updates the display screen to
reflect recent changes. This differs from the display_redraw() function in that
only changes are sent to the screen.  In most cases only a small portion of the
screen is re-drawn.

Since updating the screen tends to slow the functioning of the editor, updating
the screen is only done at intervals.  In addition, the display screen is
usually not updated while a PEL function is executing.

In writing a function, you may wish to ensure that the display reflects recent
changes at some point in the function.  For example, if you change buffers and
then use getkey() to obtain input, you will need to call display_update() for
the users to see that the current buffer has changed.

Just as flushing a file buffer ensures that the file is up to date,
display_update() ensures that the screen reflects all changes.  The changes
that are updated are changes to the contents of buffers and all other visible
contents of the display screen.

User written programs are not required to call this function.  All changes to
screen contents will be reflected in the normal course of editor operations.

____________

Value returned: No useful value is returned by the display_update() function.


ΓòÉΓòÉΓòÉ 14.6.5. done() ΓòÉΓòÉΓòÉ

done()   PEL

Purpose: Exiting the editor normally.

____________

Syntax:  void done()

____________

Description: The done() function provides an orderly exit from the editor.  It
prompts before exiting if any buffers are modified.  At that time it offers the
options of exiting without saving, cancelling the exit or writing all modified
buffers.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.6.6. execute_function() ΓòÉΓòÉΓòÉ

execute_function()   Primitive

Purpose: Calls a function with a string containing its invocation.

____________

Syntax:  any execute_function(str function_call)

____________

Description: The execute_function() function provides access to the PEL
interpreter for calling a function or making assignments to variables.  This
allows user programs to obtain a function call or variable assignment
interactively from the user. The assignment or function and arguments then need
not be known to the program.

Only constant values may be assigned to variables using this method.

There are a number of caveats and limitations when executing functions in this
manner:  Instead of placing parentheses around the arguments to the function
whitespace is used.  A space between the function name and the first argument
is sufficient.  All arguments to the function are determined by whitespace.
This may not be circumvented by the use of quotes.  As an example, consider the
string below:   message "hi there"

If this string is supplied as an argument to execute_function() it is
interpreted as follows:  Call the function named message() with the two
arguments.  The first argument is "hi and the second argument is there".

The arguments to a function executed in this manner are treated as constants --
not variables.  If you include a variable as an argument it is treated as a
string constant; no value is substituted.

____________

Value returned:

The value returned by the execute_function() function is the value returned to
it by the function it executes. If the function_call string contain an invalid
or mal-formed invocation, this function will fail and return a zero value.


ΓòÉΓòÉΓòÉ 14.6.7. invoke_function() ΓòÉΓòÉΓòÉ

invoke_function()   PEL

Purpose: Send a query or request to PEL interpreter.

____________

Syntax:  void invoke_function()

____________

Description: The invoke_function() function, normally assigned to a key, adds
functionality to execute_function().  It prompts for a string which is to be
sent to the PEL interpreter for processing.  In addition to the capabilities of
execute_function(), it allows setting and querying of global and local values,
and recognizes several functions that require special treatment. Global
variables may be set at the invoke_function() prompt using the following
format: var_name = constant

Variables local to a module are set in a similar manner except that the
variable name must be preceded by the module name and a colon:
filename:var_name= constant

Similarly, local functions may be executed using the following form:
filename:func_name The value of variables and return values of functions may be
obtained by placing a question mark at the beginning of command. For example:

 ?brief.pel:my_margin  The functions to which invoke_function() gives special
treatment are system(), dos_window(), filter() and other similar functions.
The argument string supplied to these functions requires some preprocessing.
Other functions will have their argument strings separated into arguments
strictly on the basis of whitespace with little or no preprocessing of special
characters.

____________

Value returned:

No useful value is returned by this function.  The function responds to queries
by displaying a message in the dialog window.


ΓòÉΓòÉΓòÉ 14.6.8. local_setup() ΓòÉΓòÉΓòÉ

local_setup()   PEL

Purpose: Builds in your personal preferences.

____________

Syntax: void local_setup()

____________

Description: The local_setup() function is called as part of the editor
initialization process.  Specifically, it is called by the startup() function.
It is intended as a receptacle for functions that install or establish your
personal operating preferences. For your convenience, numerous function calls
have been entered as comments within this function. This enables you to review
many of the more popular options.  You may make those you desire to use
operational by removing the pound sign ( # ) which precedes the desired option.

The options selected in the local_setup() function may be overridden by options
selected within the CPE.CFG configuration file.  This configuration file may be
used to serve a purpose similar to local_setup(), but the less information
contained in the configuration file the faster the editor will load.  It is
therefore preferable to make permanent changes to the editor's setup by way of
local_setup().

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.6.9. print_version() ΓòÉΓòÉΓòÉ

print_version()   PEL

Purpose: Shows what version of the editor is in use.

____________

Syntax: void print_version()

____________

Description: The print_version() function displays the editor version number in
the dialog window.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.6.10. process_begin() ΓòÉΓòÉΓòÉ

process_begin()   Primitive

Purpose: Initiate a nested editing process.

____________

Syntax: any process_begin()

____________

Description: The process_begin() function begins a new editing process from
within the current editing process. The new process inherits the keymap
definition in effect when the new process is begun.  All of the definitions and
buffers defined in the parent editing process are available in the new process.
This new process continues until process_end() is called. This function is
particularly useful for invoking menuing routines and pop-up utilities.  It
simplifies the writing of such functions by relieving the writer of the need to
insert numerous exit points in the function.  Instead, the process_end()
function may be assigned to a specific keystroke, and the new process continues
until that key sequence is entered.

____________

Value returned: The value returned by this function is determined by the
process_end() function which terminates it. The return value is passed as an
argument to the process_end() function.


ΓòÉΓòÉΓòÉ 14.6.11. process_end() ΓòÉΓòÉΓòÉ

process_end()   Primitive

Purpose: Terminate a nested editing process.

____________

Syntax: void process_end([any value])

____________

Description: The process_end() function causes the current editing process to
terminate.  If the editing process is nested within another process, control is
returned to the previous process.  If there is no previous editing process, the
Exit function is called.  The process, begun with process_begin() is terminated
using the value argument as its return value.

____________

Value returned: No value is returned from this function since it does not
itself return.


ΓòÉΓòÉΓòÉ 14.6.12. query_editwin_property() ΓòÉΓòÉΓòÉ

query_editwin_property()   Primitive

Purpose: Allows you to view the EWC_MAXIMIZE, EWC_NORMAL and EWC_MINIMIZE
proterties

____________

Syntax: query_editwin_property (flag)

____________

Description: This function allows you to view these properties:

EWC_MAXIMIZE   Returns TRUE if editor window is maximized, else FALSE.
EWC_NORMAL     Returns TRUE if editor window is sized in its normal state, else
               FALSE.
EWC_MINIMIZE   Returns TRUE if the editor window is minimized, else FALSE.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.6.13. quit() ΓòÉΓòÉΓòÉ

quit()   Primitive

Purpose: Exits the editor in an orderly fashion.

____________

Syntax: void quit([int code])

____________

Description: The quit() function provides a method of exiting the editor with
any necessary clean-up. The save argument, if supplied, controls the
disposition of modified buffers upon exit.  If the save argument is present,
the user is not prompted to save modified buffers.  Instead, save answers the
question that would otherwise be posed by the prompt.  When save is FALSE (0),
buffers are abandoned without saving.  When save is non-zero (TRUE), modified
buffers are saved to disk.  If save is omitted, the user is prompted to save
when modified buffers exist.  The code argument is the value to be passed to
the Exit function upon termination of the edit session.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.6.14. set_editwin_property() ΓòÉΓòÉΓòÉ

set_editwin_property()   Primitive

Purpose: To set various properties of the main editor window.

____________

Syntax: void set_editwin_property( flag )

____________

Description: This function allows you to set these properties:

EWC_TO_TOP     Brings the main editor window to the top of the PM window stack.

EWC_MAXIMIZE   Maximizes the main editor window.

EWC_NORMAL     Sizes the editor window to its non-maximized state.

EWC_MINIMIZE   Minimizes the main editor window.

____________

Value returned:  No value is returned.


ΓòÉΓòÉΓòÉ 14.6.15. toggle_file_backup() ΓòÉΓòÉΓòÉ

toggle_file_backup()   PEL

Purpose: Toggles creation of backup files.

____________

Syntax: void toggle_file_backup([int on])

____________

Description: The toggle_file_backup() function turns on or off backup file
processing.  When the on argument is zero, this feature is turned off.  Other
values for on turn it on.  When the on argument is omitted, the feature is
toggled to its opposite condition.

The location where backup files are created is determined by the
backup_directory variable.  The extension applied to the backup file is set by
the backup_file_ext variable.  When these two variables are set to their
default values, backups will be made under the original filename in a
subdirectory named BACKUP on the current drive.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.6.16. toggle_status_bar() ΓòÉΓòÉΓòÉ

toggle_status_bar()   PEL

Purpose:  Sets or toggles the status bar.

____________

Syntax:   toggle_status_bar( enable )

____________

Arguments:

o enable - forced direction of toggle

Description: If the optional parameter enable is specified, it forces the
status bar to toggle either on if TRUE, or off if FALSE.  If the parameter is
not specified, the current state of status bar is toggled.

____________

Value returned:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.6.17. toggle_stb_flags() ΓòÉΓòÉΓòÉ

toggle_stb_flags()   PEL

Purpose:  Toggles the value of the search_flags variable.

____________

Syntax:   toggle_stb_flags([long mask, long value])

____________

Arguments:

o mask - status_bar_flags bit to toggle
o on - forced direction of toggle

Description: toggle_stb_flags() changes the state of the bit in
status_bar_flags specified by the mask argument.  If the optional argument,
value, is supplied, the bit changes to that value.  Otherwise the state of the
bit toggles.

____________

Value returned:  TRUE  -  mask bit of status_bar_flags was turned on
FALSE -  the bit was turned off

See also: status_bar_flags


ΓòÉΓòÉΓòÉ 14.6.18. tracking_bottom ΓòÉΓòÉΓòÉ

tracking_bottom   read only,   Primitive

Purpose:  Bottom side of the tracking rectangle.

____________

Type:  int tracking_bottom

____________

Description:  When you create a new window by clicking your mouse and dragging
across the main editor window, the value of the bottom left corner is set just
before EVENT_TRACKING_DONE is generated.  The tracking_bottom variable contains
the value of the window's lowest, or bottom, position.

____________

See also: EVENT_TRACKING_DONE, tracking_width, tracking_height, tracking_left


ΓòÉΓòÉΓòÉ 14.6.19. tracking_height ΓòÉΓòÉΓòÉ

tracking_height   read only,   Primitive

Purpose:  Height of tracking rectangle.

____________

Type:  int tracking_height

____________

Description:  When you create a new window by clicking your mouse and dragging
across the main editor window, the value of the window height is set just
before EVENT_TRACKING_DONE is generated.  The tracking_height variable contains
the value of the window height, in pixels.

____________

See also:  EVENT_TRACKING_DONE, tracking_width, tracking_left, tracking_bottom


ΓòÉΓòÉΓòÉ 14.6.20. tracking_left ΓòÉΓòÉΓòÉ

tracking_left   read only,   Primitive

Purpose:  Left side of tracking rectangle.

____________

Type:  int tracking_left

____________

Description:  When you create a new window by clicking your mouse and dragging
across the main editor window, the value of the window height is set just
before EVENT_TRACKING_DONE is generated.  The tracking_left variable contains
the y value of the lower left corner of the new window.

____________

See also:  EVENT_TRACKING_DONE, tracking_height, tracking_bottom,
tracking_width


ΓòÉΓòÉΓòÉ 14.6.21. tracking_width ΓòÉΓòÉΓòÉ

tracking_width    read only,   Primitive

Purpose:  Width of tracking rectangle.

____________

Type:  int tracking_width

____________

Description: When you create a new window by clicking your mouse and dragging
across the main editor window, the value of the window width is set just before
EVENT_TRACKING_DONE is generated.  The tracking_width variable contains the
value of the window's width, in pixels.

____________

See also:  EVENT_TRACKING_DONE, tracking_bottom, tracking_height, tracking_left


ΓòÉΓòÉΓòÉ 14.6.22. update_current_view() ΓòÉΓòÉΓòÉ

update_current_view()   Primitive

Purpose:  To update the display of the current window.

____________

Syntax:   update_current_view()

____________

Arguments:  none

Description: This function will update the display of the current window, and
is different from display_update() in that it will only update the current
window, not every visible instance of the current buffer in a window.  If you
wish to do the minimal amount of redrawing necessary, this is the function to
call.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.6.23. write_and_exit() ΓòÉΓòÉΓòÉ

write_and_exit()   PEL

Purpose:  Save all buffers and exit the editor.

____________

Syntax:   void write_and_exit()

____________

Arguments: none.

Description: The write_and_exit() function is used to save all modified buffers
and to exit the editor immediately after.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.7. Event Handling ΓòÉΓòÉΓòÉ

Events are occurrences that are significant to a task.  Some events require
special attention.  For example, when your birthday comes around each year,
that is an event.  On that day (at the very least) you deserve special
attention.  Within an editing environment such as PREDITOR/2 there are many
events that require special treatment.  Most of these events can occur at any
time without warning.

To write an extension language program that constantly checks at every stage to
see if any events need handling would be very tedious.  Instead, PREDITOR/2 has
an event handling system that handles events for you.  You need only tell the
editor the name of one or more functions to run, and the event, whether
pre-defined or user-defined, that will cause the function to be run.

attach_event_handler()
          Associates a function with an event.
delete_event()
          Removes association between an event and a function.
execute_event_handler()
          Executes the functions associated with an event.
new_edit_file()
          Performs extension dependent tasks upon load.
query_event()
          Determine what functions are bound to an event.


ΓòÉΓòÉΓòÉ 14.7.1. attach_event_handler() ΓòÉΓòÉΓòÉ

attach_event_handler()   Primitive

Purpose: Associates a function with an event.

____________

Syntax:  int attach_event_handler(int event, funcid id)

____________

Description: The attach_event_handler() function designates a function to be
executed whenever the event identified by the event argument occurs.  The event
argument specifies the event by number and the id argument provides the
function's numeric id.  A listing of the event constants follows:

o EVENT.ACTIVATE
o EVENT.BUFFER_CREATED
o EVENT.CLOSING_REMOTE_WINDOW
o EVENT.CTRL_BREAK
o EVENT.DEACTIVATE
o EVENT.DELETE_CHARS
o EVENT.DELETING_BUFFER
o EVENT.DELETING_WINDOW
o EVENT.DISPLAY_UPDATE
o EVENT.EDITOR_RUNNING
o EVENT.EDIT_FILE_SAVE
o EVENT.EMULATION_CHANGED
o EVENT.ERROR
o EVENT.EXIT_EDITOR
o EVENT.FILE_DROPPED
o EVENT.FIRST_MOD
o EVENT.FUNCTION_CHANGED
o EVENT.HELP_INVOKED
o EVENT.IDLE_THRESHOLD
o EVENT.IDLE_TIME
o EVENT.INSERT_KEY
o EVENT.INSERT_NEWLINE
o EVENT.INSERT_STRING
o EVENT.INVALID_PCHAR
o EVENT.KEYPRESS
o EVENT.KEYPRESS_AFTER
o EVENT.LMOUSE_DRAG
o EVENT.MENU_COMMAND
o EVENT.MMOUSE_DRAG
o EVENT.MOUSE_LEFT_CLICK1
o EVENT.MOUSE_LEFT_CLICK2
o EVENT.MOUSE_LEFT_DOWN
o EVENT.MOUSE_LEFT_UP
o EVENT.MOUSE_MID_CLICK1
o EVENT.MOUSE_MID_CLICK2
o EVENT.MOUSE_MID_DOWN
o EVENT.MOUSE_MID_UP
o EVENT.MOUSE_RIGHT_CLICK1
o EVENT.MOUSE_RIGHT_CLICK2
o EVENT.MOUSE_RIGHT_DOWN
o EVENT.MOUSE_RIGHT_UP
o EVENT.NEW_CURNT_BUFFER
o EVENT.NEW_CURNT_SCREEN
o EVENT.NEW_CURNT_WINDOW
o EVENT.NEW_EDIT_FILE
o EVENT.NEW_EMPTY_BUFFER
o EVENT.NEW_SCREEN_SIZE
o EVENT.PAGECHANGED
o EVENT.PIPE_DATA
o EVENT.PROCESS_COMPLETE
o EVENT.READ_ONLY_MOD
o EVENT.RESIZE_EDITWIN
o EVENT.RMOUSE_DRAG
o EVENT.SCROLL_HORZ
o EVENT.SCROLL_VERT
o EVENT.SHELL_EXIT
o EVENT.SYSTEM_MENU_KEY
o EVENT.TEMP_SPACE_OVFLW
o EVENT.TOOLBAR_COMMAND
o EVENT_TRACKING_DONE
o EVENT.UNASSGN_KEY
o EVENT.WINDOW_MODE_CHANGE

More information on these events may be found in the "Event Handling" chapter
in Part One of this manual.

The association created by this function is not exclusive.  Other functions may
also be associated with the event and other events may cause the indicated
function to be executed.  The functions attached to an event are executed in
the reverse order from which they were attached.

____________

Value returned:

Upon successful completion, the attach_event_handler() function returns a
non-zero (TRUE) value.  If the event argument is not a valid event or the id
argument is not a defined function id, the function will fail.  A value of zero
(FALSE) is then returned.


ΓòÉΓòÉΓòÉ 14.7.1.1. EVENT.ACTIVATE ΓòÉΓòÉΓòÉ

This event is generated when a text window in the editor is activated.  This
usually happens when the window doesn't have focus and you click on it with the
mouse.


ΓòÉΓòÉΓòÉ 14.7.1.2. EVENT.BUFFER_CREATED ΓòÉΓòÉΓòÉ

EVENT.BUFFER_CREATED "New Buffer Created"

This event is generated when a new buffer is created.


ΓòÉΓòÉΓòÉ 14.7.1.3. EVENT.CLOSING_REMOTE_WINDOW ΓòÉΓòÉΓòÉ

EVENT.CLOSING_REMOTE_WINDOW "Remote Window Closing"

This event is generated when a remote window is closed through the system menu.

Example

This event is used to clean up after the Pel Debugger when the user closes it
through its system menu.


ΓòÉΓòÉΓòÉ 14.7.1.4. EVENT.CTRL_BREAK ΓòÉΓòÉΓòÉ

EVENT.CTRL_BREAK


ΓòÉΓòÉΓòÉ 14.7.1.5. EVENT.DEACTIVATE ΓòÉΓòÉΓòÉ

This event is generated when a text window loses the active state.  This
usually happens when you click on another window with the mouse.


ΓòÉΓòÉΓòÉ 14.7.1.6. EVENT.DELETE_CHARS ΓòÉΓòÉΓòÉ

EVENT.DELETE_CHARS "Character(s) Deleted from Buffer"

This event is generated when a character is deleted from the current buffer.


ΓòÉΓòÉΓòÉ 14.7.1.7. EVENT.DELETING_BUFFER ΓòÉΓòÉΓòÉ

EVENT.DELETING_BUFFER "Buffer Being Deleted"

This event is generated just before a buffer that is being deleted is actually
deleted.  Even though the buffer being deleted might not have been the current
buffer, for the duration of the event the current_buffer variable is set to the
buffer being deleted.

Example:

This might be used to perform some sort of cleanup operation on a file of a
particular type.


ΓòÉΓòÉΓòÉ 14.7.1.8. EVENT.DELETING_WINDOW ΓòÉΓòÉΓòÉ

EVENT.DELETING_WINDOW "Window Being Deleted"

This event is generated just before a window that is being deleted is actually
deleted.  Even though the window being deleted might not have been the current
window, for the duration of the event the current_window variabled is set to
the window being deleted.

Example

This might be used in MDI mode to re-tile all of the remaining windows by first
hiding the window that is going to be deleted, and then tiling.


ΓòÉΓòÉΓòÉ 14.7.1.9. EVENT.DISPLAY_UPDATE ΓòÉΓòÉΓòÉ

EVENT.DISPLAY_UPDATE


ΓòÉΓòÉΓòÉ 14.7.1.10. EVENT.EDITOR_RUNNING ΓòÉΓòÉΓòÉ

EVENT.EDITOR_RUNNING "Editor Up and Running"

This event is generated when the editor has finished initialization and is
"ready to use."


ΓòÉΓòÉΓòÉ 14.7.1.11. EVENT.EDIT_FILE_SAVE ΓòÉΓòÉΓòÉ

EVENT.EDIT_FILE_SAVE


ΓòÉΓòÉΓòÉ 14.7.1.12. EVENT.EMULATION_CHANGED ΓòÉΓòÉΓòÉ

EVENT.EMULATION_CHANGED


ΓòÉΓòÉΓòÉ 14.7.1.13. EVENT.ERROR ΓòÉΓòÉΓòÉ

EVENT.ERROR "Error Ocurred"

This event is generated when an error has been reported through the error()
function.  This will catch most, but not all errors generated while pel is
executing.


ΓòÉΓòÉΓòÉ 14.7.1.14. EVENT.EXIT_EDITOR ΓòÉΓòÉΓòÉ

EVENT.EXIT_EDITOR "Shell Process Exited"

This event is generated when a process started in the background through
system() completes.


ΓòÉΓòÉΓòÉ 14.7.1.15. EVENT.FILE_DROPPED ΓòÉΓòÉΓòÉ

EVENT.FILE_DROPPED "File Dropped on Editor"

This event is generated when a file object is dropped onto the editor in the
OS/2 Workplace Shell.  The variable dropped_file contains the fully- qualified
path of the file dropped.

Example

This event is used to handle Drag 'n Drop from the Workplace Shell.


ΓòÉΓòÉΓòÉ 14.7.1.16. EVENT.FIRST_MOD ΓòÉΓòÉΓòÉ

EVENT.FIRST_MOD "First Modification of Current Buffer"

This event is generated upon the first modification of the current buffer.


ΓòÉΓòÉΓòÉ 14.7.1.17. EVENT.FUNCTION_CHANGED ΓòÉΓòÉΓòÉ

EVENT.FUNCTION_CHANGED


ΓòÉΓòÉΓòÉ 14.7.1.18. EVENT.HELP_INVOKED ΓòÉΓòÉΓòÉ

EVENT.HELP_INVOKED


ΓòÉΓòÉΓòÉ 14.7.1.19. EVENT.IDLE_THRESHOLD ΓòÉΓòÉΓòÉ

EVENT.IDLE_THRESHOLD


ΓòÉΓòÉΓòÉ 14.7.1.20. EVENT.IDLE_TIME ΓòÉΓòÉΓòÉ

EVENT.IDLE_TIME


ΓòÉΓòÉΓòÉ 14.7.1.21. EVENT.INSERT_KEY ΓòÉΓòÉΓòÉ

EVENT.INSERT_KEY "Key Inserted Into Buffer"

This event is generated when a single character has been inserted into the
current buffer.


ΓòÉΓòÉΓòÉ 14.7.1.22. EVENT.INSERT_NEWLINE ΓòÉΓòÉΓòÉ

EVENT.INSERT_NEWLINE "Newline Inserted Into Buffer"

This event is generated when a new line is inserted into the current buffer.


ΓòÉΓòÉΓòÉ 14.7.1.23. EVENT.INSERT_STRING ΓòÉΓòÉΓòÉ

EVENT.INSERT_STRING "String Inserted Into Buffer"

This event is generated when a string has been inserted into the current
buffer.


ΓòÉΓòÉΓòÉ 14.7.1.24. EVENT.INVALID_PCHAR ΓòÉΓòÉΓòÉ

EVENT.INVALID_PCHAR "Invalid Prompt Character"

Example: This event is used to impliment the expansion of command-line commands
in the command dialog.  The tab character is an invalid pchar, and triggers the
event which expands your command.


ΓòÉΓòÉΓòÉ 14.7.1.25. EVENT.KEYPRESS ΓòÉΓòÉΓòÉ

EVENT.KEYPRESS "Key Pressed"

This event in not triggered by non-character keys that do not have functions
attached to them.

Example

This event is used to implement temporary selections with the mouse. When you
highlight a block with the mouse and then press a key, the highlighted block is
removed in an EVENT.KEYPRESS handler.


ΓòÉΓòÉΓòÉ 14.7.1.26. EVENT.KEYPRESS_AFTER ΓòÉΓòÉΓòÉ

EVENT.KEYPRESS_AFTER "After Key Pressed"

This event is generated after the function bound to a key has been been
executed.  This event is not triggered by non-character keys.


ΓòÉΓòÉΓòÉ 14.7.1.27. EVENT.LMOUSE_DRAG ΓòÉΓòÉΓòÉ

EVENT.LMOUSE_DRAG "Left Button Dragged"

DRAG is generated when the mouse pointer is moved while holding down a mouse
button.


ΓòÉΓòÉΓòÉ 14.7.1.28. EVENT.MENU_COMMAND ΓòÉΓòÉΓòÉ

EVENT.MENU_COMMAND "Menu Command"

This event is generated whenever a menu item is chosen.  The menu function has
already been executed.


ΓòÉΓòÉΓòÉ 14.7.1.29. EVENT.MMOUSE_DRAG ΓòÉΓòÉΓòÉ

EVENT.MMOUSE_DRAG "Middle Button Dragged"

DRAG is generated when the mouse pointer is moved while holding down a mouse
button.


ΓòÉΓòÉΓòÉ 14.7.1.30. EVENT.MOUSE_LEFT_CLICK1 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_LEFT_CLICK1


ΓòÉΓòÉΓòÉ 14.7.1.31. EVENT.MOUSE_LEFT_CLICK2 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_LEFT_CLICK2


ΓòÉΓòÉΓòÉ 14.7.1.32. EVENT.MOUSE_LEFT_DOWN ΓòÉΓòÉΓòÉ

EVENT.MOUSE_LEFT_DOWN


ΓòÉΓòÉΓòÉ 14.7.1.33. EVENT.MOUSE_LEFT_UP ΓòÉΓòÉΓòÉ

EVENT.MOUSE_LEFT_UP


ΓòÉΓòÉΓòÉ 14.7.1.34. EVENT.MOUSE_MID_CLICK1 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_MID_CLICK1


ΓòÉΓòÉΓòÉ 14.7.1.35. EVENT.MOUSE_MID_CLICK2 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_MID_CLICK2


ΓòÉΓòÉΓòÉ 14.7.1.36. EVENT.MOUSE_MID_DOWN ΓòÉΓòÉΓòÉ

EVENT.MOUSE_MID_DOWN


ΓòÉΓòÉΓòÉ 14.7.1.37. EVENT.MOUSE_MID_UP ΓòÉΓòÉΓòÉ

EVENT.MOUSE_MID_UP


ΓòÉΓòÉΓòÉ 14.7.1.38. EVENT.MOUSE_RIGHT_CLICK1 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_RIGHT_CLICK1


ΓòÉΓòÉΓòÉ 14.7.1.39. EVENT.MOUSE_RIGHT_CLICK2 ΓòÉΓòÉΓòÉ

EVENT.MOUSE_RIGHT_CLICK2


ΓòÉΓòÉΓòÉ 14.7.1.40. EVENT.MOUSE_RIGHT_DOWN ΓòÉΓòÉΓòÉ

EVENT.MOUSE_RIGHT_DOWN


ΓòÉΓòÉΓòÉ 14.7.1.41. EVENT.MOUSE_RIGHT_UP ΓòÉΓòÉΓòÉ

EVENT.MOUSE_RIGHT_UP


ΓòÉΓòÉΓòÉ 14.7.1.42. EVENT.NEW_CURNT_BUFFER ΓòÉΓòÉΓòÉ

EVENT.NEW_CURNT_BUFFER


ΓòÉΓòÉΓòÉ 14.7.1.43. EVENT.NEW_CURNT_SCREEN ΓòÉΓòÉΓòÉ

EVENT.NEW_CURNT_SCREEN


ΓòÉΓòÉΓòÉ 14.7.1.44. EVENT.NEW_CURNT_WINDOW ΓòÉΓòÉΓòÉ

EVENT.NEW_CURNT_WINDOW


ΓòÉΓòÉΓòÉ 14.7.1.45. EVENT.NEW_EDIT_FILE ΓòÉΓòÉΓòÉ

EVENT.NEW_EDIT_FILE


ΓòÉΓòÉΓòÉ 14.7.1.46. EVENT.NEW_EMPTY_BUFFER ΓòÉΓòÉΓòÉ

EVENT.NEW_EMPTY_BUFFER "New Scratch Buffer Created"

This event is generated when a new scratch buffer is created.


ΓòÉΓòÉΓòÉ 14.7.1.47. EVENT.NEW_SCREEN_SIZE ΓòÉΓòÉΓòÉ

EVENT.NEW_SCREEN_SIZE


ΓòÉΓòÉΓòÉ 14.7.1.48. EVENT.PAGECHANGED ΓòÉΓòÉΓòÉ

EVENT.PAGECHANGED


ΓòÉΓòÉΓòÉ 14.7.1.49. EVENT.PIPE_DATA ΓòÉΓòÉΓòÉ

EVENT.PIPE_DATA "Pipe Data Received"

This event is generated when data is sent to an OS/2 Pipe.  The variable
pipe_data contains the string of data, process_id contains the id of the
process which sent the data to the pipe, and process_pipe is the id of the
pipe.

Example

This event is used to implement the Command box from the Tools menu.


ΓòÉΓòÉΓòÉ 14.7.1.50. EVENT.PROCESS_COMPLETE ΓòÉΓòÉΓòÉ

EVENT.PROCESS_COMPLETE "Pipe Process Complete"

This event is generated when a process using pipes has completed.  The variable
process_id contains the id of the process that caused the
EVENT.PROCESS_COMPLETE, process_rc contains the return code of the process_id
process, and process_pipe contains the id of process_id's pipe.


ΓòÉΓòÉΓòÉ 14.7.1.51. EVENT.READ_ONLY_MOD ΓòÉΓòÉΓòÉ

EVENT.READ_ONLY_MOD


ΓòÉΓòÉΓòÉ 14.7.1.52. EVENT.RESIZE_EDITWIN ΓòÉΓòÉΓòÉ

EVENT.RESIZE_EDITWIN "Editor Window is Resizing"

This event is generated when the editor window is resized.

Example

This event is used in Tools/Vcs/Vdiff to keep two side-by-side windows sized
proportionally when the editor window is resized.


ΓòÉΓòÉΓòÉ 14.7.1.53. EVENT.RMOUSE_DRAG ΓòÉΓòÉΓòÉ

EVENT.RMOUSE_DRAG "Right Button Dragged"

DRAG is generated when the mouse pointer is moved while holding down a mouse
button.


ΓòÉΓòÉΓòÉ 14.7.1.54. EVENT.SCROLL_HORZ ΓòÉΓòÉΓòÉ

EVENT.SCROLL_HORZ


ΓòÉΓòÉΓòÉ 14.7.1.55. EVENT.SCROLL_VERT ΓòÉΓòÉΓòÉ

EVENT.SCROLL_VERT


ΓòÉΓòÉΓòÉ 14.7.1.56. EVENT.SHELL_EXIT ΓòÉΓòÉΓòÉ

EVENT.SHELL_EXIT


ΓòÉΓòÉΓòÉ 14.7.1.57. EVENT.SYSTEM_MENU_KEY ΓòÉΓòÉΓòÉ

EVENT.SYSTEM_MENU_KEY


ΓòÉΓòÉΓòÉ 14.7.1.58. EVENT.TEMP_SPACE_OVFLW ΓòÉΓòÉΓòÉ

EVENT.TEMP_SPACE_OVFLW


ΓòÉΓòÉΓòÉ 14.7.1.59. EVENT.TOOLBAR_COMMAND ΓòÉΓòÉΓòÉ

EVENT.TOOLBAR_COMMAND "Toolbar Command"

This event is generated whenever a toolbar button is clicked on. The button
function has already been executed.


ΓòÉΓòÉΓòÉ 14.7.1.60. EVENT_TRACKING_DONE ΓòÉΓòÉΓòÉ

EVENT_TRACKING_DONE This event is generated when you drag the mouse on the
desktop of the editor when in MDI mode.

See also: tracking_height, tracking_width, tracking_left, tracking_bottom


ΓòÉΓòÉΓòÉ 14.7.1.61. EVENT.UNASSGN_KEY ΓòÉΓòÉΓòÉ

EVENT.UNASSGN_KEY


ΓòÉΓòÉΓòÉ 14.7.1.62. EVENT.WINDOW_MODE_CHANGE ΓòÉΓòÉΓòÉ

EVENT.WINDOW_MODE_CHANGE "Window Mode Changing"

This event is generated when a window's state is changed through
restore_window(), hide_window(), expand_window(), collapse_window(). This event
will not be generated when the user clicks on the minimize or maximize buttons
of a window.


ΓòÉΓòÉΓòÉ 14.7.2. delete_event() ΓòÉΓòÉΓòÉ

delete_event()   Primitive

Purpose: Removes association between an event and a function.

____________

Syntax:  int delete_event(int event, funcid id)

____________

Description: The delete_event() function breaks the association between the
event indicated by the event argument and the function specified by id.  After
executing delete_event(), the named function will not be executed automatically
when the event is triggered.  Other functions associated with the event will
still be executed.

____________

Value returned: Upon successful completion, the delete_event() function returns
a non-zero (TRUE) value.  If the event argument is not a valid event or the id
argument is not a function id associated with that event, the function will
fail.  A value of zero (FALSE) is then returned.


ΓòÉΓòÉΓòÉ 14.7.3. execute_event_handler() ΓòÉΓòÉΓòÉ

execute_event_handler()   Primitive

Purpose: Executes the functions associated with an event.

____________

Syntax:  int execute_event_handler(int event)

____________

Description: The execute_event_handler(). function causes all of the functions
associated with an event to be executed just as if the event had occurred.  The
event to be triggered is indicated by the event argument.

____________

Value returned:

Upon successful completion, the execute_event_handler() function returns a
non-zero (TRUE) value.  If the event argument is not a valid event, the
function will fail.  A value of zero (FALSE) is then returned.


ΓòÉΓòÉΓòÉ 14.7.4. new_edit_file() ΓòÉΓòÉΓòÉ

new_edit_file()   PEL

Purpose: Performs extension dependent tasks upon load.

____________

Syntax: void new_edit_file()

____________

Description: The new_edit_file() function is an event handler designed to
perform filename extension dependent tasks when a new file is read in for
editing.  It attempts to execute a user-written function whose name is based on
the filename extension of the new file.

The name of the function is the same as filename extension prefixed with an
underscore.  For example, if a file with the extension .COB is loaded,
new_edit_file() attempts to execute a function called _cob.  If the extension
is .C it executes a function named _c.

This function must be installed with the attach_event_handler() function before
it will be effective.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.7.5. query_event() ΓòÉΓòÉΓòÉ

query_event   Primitive

Purpose:  Determine what functions are bound to an event.

____________

Syntax:   str query_event(long num)

____________

Arguments:

o num - event id

Description: The query_event() function is used to find out what functions are
bound to an event.  This is useful before using an attach_event_handler() so
the same function is not bound twice to an event.

____________

Value returned: An array of the functions bound to the event.


ΓòÉΓòÉΓòÉ 14.8. Gui Dialog ΓòÉΓòÉΓòÉ

about_dialog()
          Displays information about the product
bookmark_list()
          To display the list of current bookmarks.
buffer_list()
          Shows summary of defined buffers.
color_dialog()
          Displays a color dialog box
display_error_file_key()
          To parse an error file and display errors in a list dialog.
font_dialog()
          To display the font dialog.
gui_change()
          Invoke the cahnge dialog
gui_command()
          To display the command dialog.
gui_font_dialog()
          To display the font dialog.
gui_open()
          To open a file by prompting the user with the standard file dialog.
gui_print()
          To display the print dialog.
gui_print_select()
          To display the printer select dialog.
gui_save()
          To save the current buffer, prompting the user for a filename through
          the saveas_dialog() if it is a scratch buffer.
gui_saveas()
          To prompt the user for a file name to save the current buffer as
          through the saveas_dialog().
keys_dialog()
          To display the keys dialog.
open_dialog()
          Displays an open dialog box
print_dialog()
          Displays a print dialog box
saveas_dialog()
          Displays a save as dialog box


ΓòÉΓòÉΓòÉ 14.8.1. about_dialog() ΓòÉΓòÉΓòÉ

about_dialog()   Primitive

Purpose: Displays information about the product

____________

Syntax: void about_dialog()

____________

Description: The about_dialog() function displays version and license
information about the currently installed product.

____________

Value returned: The about_dialog() function does not return a value.


ΓòÉΓòÉΓòÉ 14.8.2. bookmark_list() ΓòÉΓòÉΓòÉ

bookmark_list()   PEL

Purpose:  To display the list of current bookmarks.

____________

Syntax:   bookmark_list()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.3. buffer_list() ΓòÉΓòÉΓòÉ

buffer_list()   PEL

Purpose: Shows summary of defined buffers.

____________

Syntax:  void buffer_list([int sys])

____________

Description: The buffer_list() function pops up a list of active buffers.
Buffers that are write- protected have "(R/O)" appearing after the buffer name.
You may then select and change the default buffer, save or delete a buffer.  A
usage message appears in the dialog window.

If the sys argument is supplied and is non- zero, system buffers will also be
included in this list.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.8.4. color_dialog() ΓòÉΓòÉΓòÉ

color_dialog()   Primitive

Purpose: Displays a color dialog box

____________

Syntax: void color_dialog()

____________

Description: The color_dialog() function displays a color dialog box and allows
the user to change the colors relating to the currently active window.

The colors that are configurable are:

o Error text on the status bar
o Help text on the status bar
o Line command color foreground and background
o Line number color foreground and background
o Message text on the status bar
o Notify text on the status bar
o Text color foreground and background
o Warning text on the status bar

____________

Value returned: The color_dialog() function does not return a value.


ΓòÉΓòÉΓòÉ 14.8.5. display_error_file_key() ΓòÉΓòÉΓòÉ

display_error_file_key()   PEL

Purpose:  To parse an error file and display errors in a list dialog.

____________

Syntax:   display_error_file_key( [str errorFileName] )

____________

Arguments:

o errorFileName - the name of the file containing error messages

Description: This function will parse a compiler error file for the type of
error(warning or error), file name, line and column number of each error.  It
will then display a list of the errors in a dialog box, from which you can view
the source code corresponding to each error.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.6. font_dialog() ΓòÉΓòÉΓòÉ

font_dialog()   Primitive

Purpose:  To display the font dialog.

____________

Syntax:   font_dialog( [long customdlg] )

____________

Arguments:

o customdlg - dialog to use

Description: If customdlg is TRUE, the editor's customized version of the
dialog, with Apply to All and Make Default buttons is used.  If customdlg is
FALSE, the standard font dialog is used.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.7. gui_change() ΓòÉΓòÉΓòÉ

gui_change()   PEL

Purpose:  Invoke the cahnge dialog

____________

Syntax:   void gui_change()

____________

Arguments: none

Description: The gui_change() function invokes the Change dialog.  The user can
enter the search and replace strings in a gui format.

____________

Value returned: none


ΓòÉΓòÉΓòÉ 14.8.8. gui_command() ΓòÉΓòÉΓòÉ

gui_command()   PEL

Purpose:  To display the command dialog.

____________

Syntax:   gui_command()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.9. gui_font_dialog() ΓòÉΓòÉΓòÉ

gui_font_dialog()   PEL

Purpose:  To display the font dialog.

____________

Syntax:   gui_font_dialog()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.10. gui_open() ΓòÉΓòÉΓòÉ

gui_open()   PEL

Purpose:  To open a file by prompting the user with the standard file dialog.

____________

Syntax:   gui_open( str initialPath )

____________

Arguments:

o initialPath - initial path for open dialog

Description:

____________

Value returned: TRUE  -  successful FALSE -  failure, user chose cancel


ΓòÉΓòÉΓòÉ 14.8.11. gui_print() ΓòÉΓòÉΓòÉ

gui_print()   PEL

Purpose:  To display the print dialog.

____________

Syntax:   gui_print()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.12. gui_print_select() ΓòÉΓòÉΓòÉ

gui_print_select()   PEL

Purpose:  To display the printer select dialog.

____________

Syntax:   gui_print_select()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.13. gui_save() ΓòÉΓòÉΓòÉ

gui_save()   PEL

Purpose:  To save the current buffer, prompting the user for a filename through
the saveas_dialog() if it is a scratch buffer.

____________

Syntax:   gui_save()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.14. gui_saveas() ΓòÉΓòÉΓòÉ

gui_saveas()   PEL

Purpose:  To prompt the user for a file name to save the current buffer as
through the saveas_dialog().

____________

Syntax:   gui_saveas( str initialPath )

____________

Arguments:

o initialPath - initial path of the saveas_dialog()

Description: This function differs from the saveas_dialog() function in that it
will not just prompt the user for a file name, but will also then save the
buffer under that name.

____________

Value returned: The value returned is the number of bytes successfully written
by write_buffer().


ΓòÉΓòÉΓòÉ 14.8.15. keys_dialog() ΓòÉΓòÉΓòÉ

keys_dialog()   PEL

Purpose:  To display the keys dialog.

____________

Syntax:   keys_dialog()

____________

Arguments:  none

Description: This dialog will enable you to change your key assignments as you
wish.  Many of the utility functions in the editor do not have default key
assignments because they are not a strict part of any emulation.  Through this
dialog, you can assign your most oft-used function to keystrokes, thus saving
yourself much typing time.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.8.16. open_dialog() ΓòÉΓòÉΓòÉ

open_dialog()   Primitive

Purpose: Displays an open dialog box

____________

Syntax: string  open_dialog(string default_file,string title)

____________

Description: The open_dialog() function will display an open dialog box which
allows selection of a file.  The open dialog box displays a file list for
selecting files, a directory list for displaying files in different
directories, and a drives list for displaying files on different drives.  The
open_dialog() function does not open the file selected.  The function only
returns the filename selected.  The open_dialog() function will allow multiple
selected filenames.  Multiple filenames are return in a semi-colon delimited
string.  The default_file argument contains the initial file or wildcard
selection displayed in the open dialog box.  If default_file contains a drive
and/or directory name then the open dialog box will update the directory and
drive lists respectively.  The title argument contains the title of the dialog
box when it is displayed.

____________

Value returned: The value returned by open_dialog() is the full path name of
the file selected from the open dialog box.


ΓòÉΓòÉΓòÉ 14.8.17. print_dialog() ΓòÉΓòÉΓòÉ

print_dialog()   Primitive

Purpose: Displays a print dialog box

____________

Syntax: short print_dialog()

____________

Description: The print_dialog() function displays a dialog box that allows the
user to configure print jobs from within the editor.

____________

Value returned: The print_dialog() function returns the result of the dialog.
If a non-zero value is returned the Print button was selected otherwise the
cancel button was selected.


ΓòÉΓòÉΓòÉ 14.8.18. saveas_dialog() ΓòÉΓòÉΓòÉ

saveas_dialog()   Primitive

Purpose: Displays a save as dialog box

____________

Syntax: string saveas_dialog(string default_file)

____________

Description: The saveas_dialog() function displays a dialog box that allows
selection of a file.  The save as dialog box displays a file list for selecting
files, a directory list for displaying files in different directories, and a
drives list for displaying files on different drives.  The saveas_dialog()
function does not save the current buffer. The user is responsible for saving
the file after the file name is returned.  The default_file argument is the
initial file name displayed in the in the save as dialog box.

____________

Value returned: The value returned by saveas_dialog() is the full path name of
the file selected from the save as dialog box.


ΓòÉΓòÉΓòÉ 14.9. Help ΓòÉΓòÉΓòÉ

attach_help()
          Attaches a help file to the editor or a dialog box
delete_help()
          Removes a help_file assocation
display_help()
          Displays help for the key passed in.
display_help_item()
          To display on-line help on a string.
gui_help_index()
          To display the help index.
load_ndx_help()
          To initialize the NDX file system.
ndx_help()
          To look up help for a symbol in an ndx file.
user_help_lines()
          Entry point for user defined help.


ΓòÉΓòÉΓòÉ 14.9.1. attach_help() ΓòÉΓòÉΓòÉ

attach_help()   Primitive

Purpose: Attaches a help file to the editor or a dialog box

____________

Syntax: void attach_help(string help_file[, long dlgid ] )

____________

Description: The attach_help() function attaches a help file to either a dialog
box or the editor.  The attach_help() function call must be called before any
calls to display_help().  The display_help() function uses the help file
associated with a window to display help information. If attach_help() is not
called before display_help(), no help information will be displayed.  The
help_file argument contains the name of the help file.  Under OS/2 this file
must be a .HLP file that was created with the IPFC compiler.  The optional
dlgid argument contains the id of the dialog box that the help file is
associated with.  If this value is not specified the help file is associated
with the editor window.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.9.2. delete_help() ΓòÉΓòÉΓòÉ

delete_help()   Primitive

Purpose: Removes a help_file assocation

____________

Syntax: void delete_help( [ long dlgid ] )

____________

Description: The delete_help() function removes the association between a help
file and a window.  The delete_help() function should be used if a help file is
no longer needed.  The optional dlgid argument contains the id of the dialog
box whose help file is deleted.  If this argument is not given the help file
associated with the editor window is deleted.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.9.3. display_help() ΓòÉΓòÉΓòÉ

display_help()   Primitive

Purpose: Displays help for the key passed in.

____________

Syntax: short display_help( any key [, long dlgid] )

____________

Description: The display_help() function displays help that is associated with
the key that is passed in.  The argument passed in must be a string or a long.
The display_help() function will use the currently loaded help file established
with attach_help().

There are some standard reserved keys that are used by the help system.

Reserved keys:          Meaning:
HelpTOC                 Display the table of contents.
HelpIndex               Display help index.
HelpOnHelp              Display help on help system itself.

____________

Value returned: This function returns zero for success and non-zero for
failure.

____________

See also: attach_help(), delete_help()


ΓòÉΓòÉΓòÉ 14.9.4. display_help_item() ΓòÉΓòÉΓòÉ

display_help_item()   PEL

Purpose:  To display on-line help on a string.

____________

Syntax:   display_help_item( str item )

____________

Arguments:

o item - the name of the help item to display help on.

Description: First searches the NDX help previously loaded with the
load_ndx_help() function for the item.  If it is not found, then the editor's
help file is invoked to look up the item.  If it is still not found, the help
system will display an error message stating that the topic could not be found.

Note: If the item is not passed, the symbol under the cursor is used.

____________

Value returned:  None

____________

See also:  first_help, fast_help, ndx_help(), load_ndx_help()


ΓòÉΓòÉΓòÉ 14.9.5. gui_help_index() ΓòÉΓòÉΓòÉ

gui_help_index()   PEL

Purpose:  To display the help index.

____________

Syntax:   gui_help_index()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.9.6. load_ndx_help() ΓòÉΓòÉΓòÉ

load_ndx_help()   PEL

Purpose:  To initialize the NDX file system.

____________

Syntax:   load_ndx_help()

____________

Arguments:  None.

Description: This function will load all the .ndx files specified in the
HELPNDX environment variable.  The DPATH environment variable is searched to
locate the .ndx files After initializing the NDX help system, context-sensitive
or keyword help will search the loaded .ndx files for help on the word at the
current cursor location.

____________

Value returned:  None.

____________

See also: ndx_help(), display_help_item()


ΓòÉΓòÉΓòÉ 14.9.7. ndx_help() ΓòÉΓòÉΓòÉ

ndx_help()   PEL

Purpose:  To look up help for a symbol in an ndx file.

____________

Syntax:   ndx_help( str symbol, [str ndx_file] )

____________

Arguments:

o symbol  - symbol to look up help for
o ndx_file - ndx file to look for help in, if not specified

Description: Before calling this function, load_ndx_help() must be called in
order to initialize the NDX help system.

____________

Value returned: TRUE  -  success, found help FALSE -  failure, could not find
help

____________

See also:  first_help, fast_help, load_ndx_help(), display_help_item()


ΓòÉΓòÉΓòÉ 14.9.8. user_help_lines() ΓòÉΓòÉΓòÉ

user_help_lines()   PEL

Purpose:  Entry point for user defined help.

____________

Syntax:   void user_help_lines(menuhndl main_menu )

____________

Arguments:

o main_menu - handle of the main menu

Description: The user_help_lines() function is the entry point for user defined
help on menus.  Help is added using the modify_menuitem() function.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.10. Key mapping ΓòÉΓòÉΓòÉ

A Keymap tells SPE what function has been assigned which keystroke.  It is a
table that the editor uses to look up which function has been associated with a
specific keystroke.  The assignments in a keymap may easily be changed, or you
may use an entirely different keymap when the current one does not serve your
purpose.

Keymaps are assigned an id number when they are created.  After creation with
the create_keymap() function, the keymap is referenced by this id.  A stack of
keymaps may be used to simplify changing from one keyboard definition to
another. Keymaps may be pushed onto and popped off of this stack using the
push_keymap() and pop_keymap() functions.

There is one primary keymap, referred to as the current keymap.  A portion or
all of the current keymap may be redefined by a keymap local to the current
buffer.  Together, these keymaps are responsible for the interpretation of all
keyboard input.  These two keymaps are identified by the current_keymap and
buffer_keymap variables.

assign_key()
          Assigns a function to a keystroke.
brief()
          Makes the editor operate similarly to the BRIEF editor.
clear_keymap()
          Deletes all key assignments from a keymap definition.
create_keymap()
          Creates new keymap in preparation for customization.
cua()
          To switch to the CUA emulation.
delete_keymap()
          Deletes a keyboard definition from the system.
emacs()
          Switch to the emacs emulation.
execute_key_action()
          Perform the function associated with a key.
function_binding()
          Reports what keys a function is bound to.
int_to_key()
          Interprets a keycode into the name-string of the key.
ispf()
          To switch to the ispf emulation.
key_to_int()
          Tells the keycode associated with the name of a key.
keymap_binding()
          Reports the name of the function assigned to a key.
learn_key()
          Records keystrokes for assignment to a key.
list_keymap()
          To list the current keymap in various formats.
native()
          Installs the native keyboard definition.
playback()
          Reissue a series of previously recorded keystrokes.
pop_keymap()
          Restore the most recently saved keyboard definition.
print_bindings()
          To read keys and display helpful information on their bindings.
push_keymap()
          Saves a keymap on the stack, makes another current.
record()
          Store keystrokes in a string for later replay.
record_key()
          record() function with messages and prompting added.
repeat_key_action()
          Repeats the key action that follows.
reset_keymap()
          Redefines the current keymap to operate like another.
scroll_lock_status()
          To report the status of the scroll lock key.
vi()
          Makes the editor operate similarly to Unix_ VI editor.


ΓòÉΓòÉΓòÉ 14.10.1. assign_key() ΓòÉΓòÉΓòÉ

assign_key()   Primitive

Purpose: Assigns a function to a keystroke.

____________

Syntax:  int assign_key(str key, str function_call)

____________

Description: The assign_key() function records a key assignment in the current
keymap.  The key argument gives the name of the key, to which a function is to
be assigned, in string form.

Within the key string, keystrokes may be represented numerically or as
descriptive strings called keynames.  The simpler method is to specify the
keystroke by keyname.

When specifying a keystroke by numeric string, the number is preceded by a
pound symbol, #.  Decimal values must be used. Hexadecimal representations are
not acceptable in this context.  The number may be the character's ASCII value
or, when you need to be more explicit, the character's key id.

Keys that can be represented by a single character may be referenced by placing
that character in the string.  A few characters are used for special purposes
and must be preceded by a backslash when used to represent themselves.  These
characters include the pound symbol, #, and angle brackets, <>.  They must be
represented in this manner:  \#, \< and \>.

Keys such as Tab, Esc and F1 whose names require more than one character to
describe must be enclosed in angle brackets, <>, as follows: <Tab>, <Esc> and
<F1>.  When a keystroke involves more than one key pressed simultaneously both
key names are placed within the angle brackets.  These keynames must be
separated by a single dash; a space or underscore is not acceptable.  A list of
these keynames appears in the "Keymapping" chapter in Part One of this manual.

The keyname and numeric methods of specifying keystrokes may be inter-mixed
within the key string, as demonstrated in the following example:

  #3a<tab>

This example describes the keystrokes  [Ctrl][C],[a],[Tab]. The function_call
argument usually gives a string containing just the name of a function to be
assigned to the key.  It may, however, contain a function name and arguments or
an assignment to a variable. Here is a typical example of an assign_key()
function assignment:

assign_key("<Alt-F10>","displayDate")

When specifying arguments to a function within the function_call string,
parentheses and commas are not used.  The name of the function and each of the
arguments are separated by spaces only:

assign_key("<Ctrl-U>","restore_position 1")

Calling this same function from within source code would use the form
restore_position(1).  This is incorrect form for assigning to a key, however.

Here is an example of the function_call argument containing a variable
assignment: assign_key("<Alt-L>","message_level = 3")

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.2. brief() ΓòÉΓòÉΓòÉ

brief()   PEL

Purpose: Makes the editor operate similarly to the BRIEF editor.

____________

Syntax:  void brief()

____________

Description: The brief() function executes a setup and installs a special
keyboard definition that causes the editor to operate like the popular BRIEF
editor.  This is one of the "emulation packages" provided with the editor.  For
a list of differences between the editor's BRIEF emulation and the BRIEF editor
see Appendix B of the User's Manual.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.3. clear_keymap() ΓòÉΓòÉΓòÉ

clear_keymap()   Primitive

Purpose: Deletes all key assignments from a keymap definition.

____________

Syntax:  int clear_keymap([keymapid keymap])

____________

Description: The clear_keymap() function removes all key assignments from the
keyboard definition described by the keymap argument.  The keymap argument is
the numeric id associated with a previously defined keyboard definition.

If the keymap argument is omitted, the keymap currently in use is initialized.
For this reason, some care should be exercised when using the clear_keymap().
function.

There is one key function which is always defined: the [Ctrl][Break] key
combination.  This key combination allows an orderly exit from the editor.

____________

Value returned:

This function returns a non-zero (TRUE) value unless an invalid keymap argument
is supplied.  In the latter case, the clear_keymap() function returns a zero
(FALSE) value.


ΓòÉΓòÉΓòÉ 14.10.4. create_keymap() ΓòÉΓòÉΓòÉ

create_keymap()   Primitive

Purpose: Creates new keymap in preparation for customization.

____________

Syntax:  keymapid create_keymap([keymapid keymap])

____________

Description: The create_keymap() function produces a new keymap that may then
be customized.  The new keymap is initialized to the values of the keymap
described by the keymap argument.  If the keymap argument is missing, the
empty_keymap is used.  If an invalid argument is specified, the function will
fail.

____________

Value returned:

The value returned by create_keymap() is the id assigned to the new keymap by
the system.  A return value of zero indicates that the function has failed.

____________

See also:  current_keymap, delete_keymap().


ΓòÉΓòÉΓòÉ 14.10.5. cua() ΓòÉΓòÉΓòÉ

cua()   PEL

Purpose:  To switch to the CUA emulation.

____________

Syntax:   cua()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.10.6. delete_keymap() ΓòÉΓòÉΓòÉ

delete_keymap()   Primitive

Purpose: Deletes a keyboard definition from the system.

____________

Syntax:  int delete_keymap(keymapid keymap)

____________

Description: The delete_keymap(). function disposes of a keymap definition and
undefines the associated id.  This function may not be performed on the keymap
currently in use. This function should be used with discretion since its use
can result in references to non-existent keyboard definitions on the keymap
stack.

____________

Value returned: The value returned by the delete_keymap(). function is non-zero
(TRUE) upon successful completion.  A return value of zero or FALSE indicates
that the function has failed.


ΓòÉΓòÉΓòÉ 14.10.7. emacs() ΓòÉΓòÉΓòÉ

emacs()   PEL

Purpose:  Switch to the emacs emulation.

____________

Syntax:   emacs()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.10.8. execute_key_action() ΓòÉΓòÉΓòÉ

execute_key_action()   PEL

Purpose: Perform the function associated with a key.

____________

Syntax:  any execute_key_action(str keys)

____________

Description: The execute_key_action() function executes the function associated
with the keystroke described by keys as if it had been typed in from the
keyboard.  The keys argument gives the name of the keystroke in string form.  A
table containing the allowable key-name strings appears in the "Keymapping"
chapter in Part One of this manual.

____________

Value returned:

This function's return value may be either a string or an integer, depending on
the value returned by the function that it executes.  If an invalid argument is
supplied, the return value will be an empty string.  If, however, a valid
key-name string is supplied but no function is associated with that keystroke,
the string value "undefined" is returned.


ΓòÉΓòÉΓòÉ 14.10.9. function_binding() ΓòÉΓòÉΓòÉ

function_binding()   Primitive

Purpose: Reports what keys a function is bound to.

____________

Syntax:  str function_binding(funcid func [, keymapid keymap])

____________

Description: The function_binding() function tells the key or keystroke
combination to which the function described by the func argument is bound.  If
func is bound to more than one keystroke, all of the associated keystrokes are
reported.  The keymap argument may be used to specify the keymap to which the
query is to apply.  If keymap is not supplied, the query applies to the current
keymap.

____________

Value returned:

The value returned by function_binding(). is a string containing the keystrokes
associated with the function.  The keystrokes take the form of the key id (scan
code and ASCII value) in decimal notation preceded by a pound sign ( # ):

  "#123#432#45565"

The example above shows a keystroke sequence of three key ids.  The function is
assigned to this combination of keys. If the function has been assigned to more
than one keystroke combination, each keystroke combination is separated from
the one preceding by a space:   "#123#432#45565 #4543 #23423"

This second example shows three different key sequences that may be used to
execute the function.  The first key sequence involves three separate key ids.


ΓòÉΓòÉΓòÉ 14.10.10. int_to_key() ΓòÉΓòÉΓòÉ

int_to_key()   Primitive

Purpose: Interprets a keycode into the name-string of the key.

____________

Syntax:  str int_to_key(int char)

____________

Description: The int_to_key() function provides the key- name string
corresponding to the key described by the char argument.  The char argument is
a keycode value such as that returned by the getkey() or getchar() keyboard
input functions.

____________

Value returned:

The value returned by the int_to_key() function is the key's descriptive
string. A table containing the key-name strings used by this function appears
in the "Keymapping" chapter in Part One of this manual.  Passing an invalid
argument to this function will result in an empty string being returned.


ΓòÉΓòÉΓòÉ 14.10.11. ispf() ΓòÉΓòÉΓòÉ

ispf()   PEL

Purpose:  To switch to the ispf emulation.

____________

Syntax:   ispf()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.10.12. key_to_int() ΓòÉΓòÉΓòÉ

key_to_int()   Primitive

Purpose: Tells the keycode associated with the name of a key.

____________

Syntax:  int key_to_int(str key)

____________

Description: The key_to_int() function provides the scan code and any ASCII
equivalent for the key described by the key argument.  The key argument is
string containing the name of a key.  A table containing the key-name strings
used by this function appears in the "Keymapping" chapter in Part One of this
manual.

____________

Value returned:

The value returned by the key_to_int() function is in the same format as that
returned by the getkey() function.  The least significant (lowest) byte
contains the ASCII value of the key and the next byte contains the scan code.
Passing an invalid argument to this function will result in a zero value
returned.


ΓòÉΓòÉΓòÉ 14.10.13. keymap_binding() ΓòÉΓòÉΓòÉ

keymap_binding()   Primitive

Purpose: Reports the name of the function assigned to a key.

____________

Syntax:  str keymap_binding(str keys [, keymapid keymap])

____________

Description: The keymap_binding() function reports what function is associated
with the keystroke or keystrokes described by the keys argument.  The keys
argument describes the keystrokes in string form.  These descriptive strings
are called key-name strings.  A table containing the allowable key-name strings
appears in the "Keymapping" chapter in Part One of this manual.

The keymap argument may be used optionally to specify that the inquiry applies
to a keyboard definition other than the one currently in use.  If the keymap
argument is omitted, the assignment reported applies to the current keymap or
the local keymap assignment, if any.

____________

Value returned:

The string returned by this function upon successful completion contains the
name of the function that will be executed when the described keystroke is
executed.

An empty string is returned if the keymap has no function assigned to the
specified key or if the key combination is not recognized.


ΓòÉΓòÉΓòÉ 14.10.14. learn_key() ΓòÉΓòÉΓòÉ

learn_key()   PEL

Purpose: Records keystrokes for assignment to a key.

____________

Syntax: void learn_key()

____________

Description: The learn_key() function is an extension of the record() and
playback() functions allowing keystroke recordings to be assigned to a specific
key.  This allows more than one series of keystrokes to be defined at a time.
When learn_key() is invoked, it requests the key combination to which the
recording is to be assigned and then recording begins.  The recording sequence
is terminated by pressing again the key to which the recording is to be
assigned.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.15. list_keymap() ΓòÉΓòÉΓòÉ

list_keymap()   PEL

Purpose:  To list the current keymap in various formats.

____________

Syntax:   list_keymap( str format, int noBrackets, int plus )

____________

Arguments:

o format - one of various output formats:
o noBrackets - whether or not to display "<>" chars
o plus - use '+' symbol instead of '-' symbol for key strings(i.e. <Alt-S>
  becomes <Alt+S> )

Description: This function is useful whenever you need a list of the key
bindings in your keymap.  Choose the formatting style that suites your purpose.
"pel" -  outputs the current keymap as a series of pel commands that you can
block copy into your own macros.  "cfg" -  outputs the current keymap as a
series of entries in the configuration file that you can block copy into your
own configuration file.  ""   -  outputs the keymap in an easy-to-read table.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.10.16. native() ΓòÉΓòÉΓòÉ

native()   PEL

Purpose: Installs the native keyboard definition.

____________

Syntax: void native()

____________

Description: The native() function executes a setup and installs the factory
keyboard definition.  This is one of the "emulation packages" provided with the
editor. Other keyboard definitions are described in the Appendices to the
User's Manual.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.17. playback() ΓòÉΓòÉΓòÉ

playback()   Primitive

Purpose: Reissue a series of previously recorded keystrokes.

____________

Syntax: int playback([str recording [, keymapid keymap]])

____________

Description: The playback() function issues the keystrokes contained in the
recording argument.  If this argument is not supplied, playback() replays the
keystrokes in the last string recorded.  These keystrokes have the effect of
being entered using the keyboard definition indicated by the keymap argument.
If the keymap argument is not specified, the keystrokes are issued through the
keymap currently in effect.

____________

Value returned: The value returned by the playback() function is non-zero
(TRUE) on successful completion.  The function will fail if a function assigned
to one of the keystrokes issued cannot be successfully completed.  It will also
fail if there is an invalid keystroke contained in the recording argument.
Upon failure, the function returns a zero (FALSE) value.


ΓòÉΓòÉΓòÉ 14.10.18. pop_keymap() ΓòÉΓòÉΓòÉ

pop_keymap()   PEL

Purpose: Restore the most recently saved keyboard definition.

____________

Syntax: int pop_keymap()

____________

Description: The pop_keymap() function restores a keymap previously saved with
the push_keymap() function. The keymap on the stack which was most recently
saved is removed from the stack and made the current keymap.

____________

Value returned: The pop_keymap() function returns a non-zero (TRUE) value.  If
there are no keymaps remaining on the stack, the function will return a zero
(FALSE) value.


ΓòÉΓòÉΓòÉ 14.10.19. print_bindings() ΓòÉΓòÉΓòÉ

print_bindings()   PEL

Purpose:  To read keys and display helpful information on their bindings.

____________

Syntax:   print_bindings()

____________

Arguments:  none

Description: When you call this function, it will keep reading the key-
combinations you press and displaying information on them until you hit the
<Esc> key.  It will then ask you if you want to terminate the sequence of key
queries or if you want information on the <Esc> key itself.  Either 'y' or
hitting <Esc> again will terminate this function, 'n' will display information
on the <Esc> key and continue.  Information displayed:  scan code(hex) scan
code(dec) ascii value key name key binding

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.10.20. push_keymap() ΓòÉΓòÉΓòÉ

push_keymap()   PEL

Purpose: Saves a keymap on the stack, makes another current.

____________

Syntax: int push_keymap([keymapid keymap])

____________

Description: The push_keymap() function saves the current keyboard definition
on the stack it shares with the pop_keymap() function.  It then makes the
keymap described by the keymap argument the new current keymap.  If the keymap
argument does not represent a valid keymap, this function does nothing but
return an error.

If the keymap argument is omitted the current keyboard definition remains the
same.  However, that keymap's id has been saved on the stack for later
restoration.

____________

Value returned: Upon successful completion, the push_keymap() function returns
a non-zero (TRUE) value.  On error this function returns a zero (FALSE) value.


ΓòÉΓòÉΓòÉ 14.10.21. record() ΓòÉΓòÉΓòÉ

record()   Primitive

Purpose: Store keystrokes in a string for later replay.

____________

Syntax: str record([int flag])

____________

Description: The record() function is used to turn on and also to turn off the
recording of keystrokes as they are entered from the keyboard.  The flag
argument is used to indicate whether recording is to be turned on or off.  When
flag is 1, recording is turned on. When flag is 0, recording is turned off.  If
this argument is omitted, recording will be toggled:  if it is on, it will be
turned off; if it is off, it will be turned on.

If recording is explicitly turned on when it is already on, the recording
process is re-initialized and previously recorded keystrokes are abandoned.
Turning recording off when it is already off has no effect.

There are a few key sequences that can't be recorded, such as [Ctrl][Break] and
[Ctrl][Alt][Del].  The rule governing what can be recorded and what cannot is
as follows:  If it can't be detected with the getkey() function it can't be
recorded.  A table of the recognized key sequences is given in the "Console
I/O" chapter in Part One of this manual. Use the record_key() function for
assignment to a keystroke.

____________

Value returned: When record() turns recording off, a string is always returned.
The string contains ASCII values corresponding to the keys that have been
typed. Each keycode is represented by two character sequences.  The string may
be empty, if no valid keystrokes are typed.  When recording is turned on, an
empty string is returned.


ΓòÉΓòÉΓòÉ 14.10.22. record_key() ΓòÉΓòÉΓòÉ

record_key()   PEL

Purpose: record() function with messages and prompting added.

____________

Syntax: str record_key()

____________

Description: The record_key() function is a version of the record() functions
more suitable for assignment to a keystroke.  It, too, turns on and off the
recording of keystrokes entered from the keyboard. This function sends a
message to the dialog window indicating whether calling the function has turned
recording on or off.

As with the record() function, it may only remember one series of keystrokes at
a time.  If another series of keystrokes has already been recorded, the user is
prompted before overwriting the previous recording.  If the record_key()
function is called while recording is already in process, the keystroke is
ignored.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.23. repeat_key_action() ΓòÉΓòÉΓòÉ

repeat_key_action()   PEL

Purpose: Repeats the key action that follows.

____________

Syntax: void repeat_key_action()

____________

Description: The repeat_key_action() function prompts the user for a number of
repetitions and then waits for the user to press a key.  It then repeats the
action associated with that key the specified number of times.  The action to
be repeated may be anything from repeatedly inserting a character into the
buffer to paging down a specified number of times.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.10.24. reset_keymap() ΓòÉΓòÉΓòÉ

reset_keymap()   Primitive

Purpose: Redefines the current keymap to operate like another.

____________

Syntax: int reset_keymap([keymapid keymap])

____________

Description: The reset_keymap() function redefines the current keymap to be a
copy of the keyboard definition described by the keymap argument.  The keymap
argument is the numeric id associated with a previously defined keyboard
definition.

If keymap is omitted, the keyboard is re- initialized to the assignments of the
system default keyboard (factory_keymap).  If keymap is supplied but does not
represent a valid keyboard, this function will fail.

____________

Value returned: The reset_keymap() function returns a non-zero (TRUE) value
upon successful completion.  If the function fails, a zero (FALSE) value is
returned.


ΓòÉΓòÉΓòÉ 14.10.25. scroll_lock_status() ΓòÉΓòÉΓòÉ

scroll_lock_status()   PEL

Purpose:  To report the status of the scroll lock key.

____________

Syntax:   scroll_lock_status()

____________

Arguments:  none

Description:

____________

Value returned: TRUE  -  scroll lock on FALSE -  scroll lock off


ΓòÉΓòÉΓòÉ 14.10.26. vi() ΓòÉΓòÉΓòÉ

vi()   PEL

Purpose: Makes the editor operate similarly to Unix_ VI editor.

____________

Syntax: void vi()

____________

Description: The vi() function configures the editor to approximate the
operation of the popular UNIX editor, VI.  This is one of the "emulation
packages" provided with the editor.

Because of certain inherent differences in the way the editor performs tasks
and the way VI performs similar tasks, this function does not attempt a
complete emulation of VI.  For a list of the keys in the editor's VI emulation
see Appendix B of the User's Manual.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.11. Menus ΓòÉΓòÉΓòÉ

append_menuitem()
          Appends a menu item to a menu.
create_menu()
          Creates a menu.
delete_menu()
          Deletes a menu
delete_menuitem()
          Removes a menu item from a menu
fix_menu_text()
          To update the menu accelerator text.
insert_menuitem()
          Inserts a menu item into a menu.
menu_functions()
          Lists the functions to execute when a menu item is selected.
menu_info()
          Retrieves information about a menu.
modify_menuitem()
          Modifies attributes of a particular menu item.
show_popup()
          Displays a popup menu
user_menu()
          Entry point for user defined help.


ΓòÉΓòÉΓòÉ 14.11.1. append_menuitem() ΓòÉΓòÉΓòÉ

append_menuitem()   Primitive

Purpose: Appends a menu item to a menu.

____________

Syntax: void append_menuitem(long menuid, short itemid, short flags, [any
itemInfo, [any itemText]])

____________

Arguments: menuid - the menu to append the item into.  The menuid argument must
have been returned by the create_menu() function.

itemid - the id of the newly created menu id.

flags - contains information on the characteristics of the menu item.  The
flags argument can be any one or more of the following combined with the or()
function:

Types of Menu Items

MI_SEPARATOR - menu item is a separator

MI_SUBMENU - menu item is a submenu

MI_MENUITEM - menu item is a normal menu item

Styles of Menu Items

MI_CHECKED - menu item is checked

MI_UNCHECKED - menu item is not checked

MI_DISABLED - menu item is disabled

MI_ENABLED - menu item is enabled

MI_DEFAULT - MI_ENABLED | MI_MENUITEM

iteminfo - depends on the type of item created according to the flags argument.

Possible Flag Values

MI_SEPARATOR - Not used.

MI_SUBMENU - Submenu id.

MI_MENUITEM - Function id of function to call when menu item is selected. Must
be a value returned from function_id().

itemText - this contains text that is displayed for the new menu item. This
argument is only used for MI_SUBMENU and MI_MENUITEM types of menu items.

help - contains an index into the program's help table.  When [F1} is pressed
on the menu item, the helpl argument will be used to display help for the
particular menu item.  The help file must have been previously loaded with the
attach_help() function.

____________

Description: The append_menuitem() function appends a menu item into a menu.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.11.2. create_menu() ΓòÉΓòÉΓòÉ

create_menu()   Primitive

Purpose: Creates a menu.

____________

Syntax: menuid create_menu([int resource_id], [str resource_dll])

____________

Arguments: resource_id - the id of the menu in the resource file

resource_dll - the name of the DLL that stores the menu resource. If this
argument is not specified, the executable will be searched for the menu
resource.

____________

Description: The create_menu() function creates a menu that can be displayed as
the main menu or as a popup menu.

The menu can be loaded from a resource file by providing the resource id
argument and optionally a resource DLL if the menu resource is not bound to the
executable file.

____________

Value returned: The new menu is returned upon success.  A zero value is
returned if the function fails.


ΓòÉΓòÉΓòÉ 14.11.3. delete_menu() ΓòÉΓòÉΓòÉ

delete_menu()   Primitive

Purpose: Deletes a menu

____________

Syntax: void delete_menu(menuid menu)

____________

Description: The delete_menu() function deletes and frees the memory associated
with the menu argument. The menu argument contains the menuid to delete and
must have been returned from the create_menu() function.

____________

Value returned: The delete_menu() function does not return a value.


ΓòÉΓòÉΓòÉ 14.11.4. fix_menu_text() ΓòÉΓòÉΓòÉ

fix_menu_text()   PEL

Purpose:  To update the menu accelerator text.

____________

Syntax:   fix_menu_text( [[int id, funcid functionid], [str prefix]] )

____________

Arguments:

o id - id of the menuitem
o functionid - function to display key bindings for
o prefix - string prefix to use

Description: This function updates the menu accelerator text to reflect the
current keymap.  This is used when the emulation mode is changed to insure that
the accelerator text is up to date. The prefix argument can be used to specify
multiple-keystroke accelerators.  When you type <Ctrl-X> in emacs, for
instance, the keymap is temporarily changed to implement the multiple-
keystroke commands that begin with <Ctrl-X>.  In the case of emacs, the prefix
argument of fix_menu_text() is set to "Ctrl+X-" while the id and functionid
arguments are set to the function assigned to <Ctrl-S> in the new keymap and
the effected menu item, respectively.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.11.5. delete_menuitem() ΓòÉΓòÉΓòÉ

delete_menuitem()   Primitive

Purpose: Removes a menu item from a menu

____________

Syntax: void delete_menuitem(menuid menu, short itemid)

____________

Description: The delete_menuitem() function will remove the specified item from
a menu. The menu argument contains the menu to remove the item from.  The menu
argument must have been returned from the create_menu() function. The itemid
argument is the id of the menu item to delete.  The item id must be the same id
as the id used in the append_menuitem() function.

____________

Value returned: The delete_menuitem() function does not return a value.


ΓòÉΓòÉΓòÉ 14.11.6. insert_menuitem() ΓòÉΓòÉΓòÉ

insert_menuitem()   Primitive

Purpose: Inserts a menu item into a menu.

____________

Syntax: void insert_menuitem(long  menuid, short itemid, short before_item_id,
short  flags,  [any itemInfo], [str itemText], [str help])

____________

Description: The insert_menuitem() function inserts a menu item into a menu.

The menuid argument is the menu to append the item into.  The menuid argument
must have been returned from the create_menu() function.

The itemid argument is the id of the newly created menu id.

The flags argument contains information on the characteristics of the menu
item.  The flags argument can be any of the following or'ed together:

Types of menu items:

MI_SEPARATOR        - menu item is a separator
MI_SUBMENU          - menu item is a submenu
MI_MENUITEM         - menu item is a normal menu item

Styles of menu item:

MI_CHECKED          - menu item is checked
MI_UNCHECKED        - menu item is not checked
MI_DISABLED         - menu item is disabled
MI_ENABLED          - menu item is enabled
MI_DEFAULT          - MI_ENABLED | MI_MENUITEM
The itemInfo argument depends on the type of item created according to the
flags argument.

Flags argument contains: ItemInfo must be:
MI_SEPARATOR            Not used
MI_SUBMENU              Submenu id
MI_MENUITEM             function id of function to call when menu item is
                        selected. Must be returned from function_id().

The itemText argument contains the text that is displayed for the new menu
item.  This argument is only used for MI_SUBMENU and MI_MENUITEM types of menu
items.

The optional help argument contains an index into the programs help table.
When F1 is pressed on the menu item, the help argument will be used to display
help for the particular menu item.  The help file must have been previously
loaded with the attach_help() function.

____________

Value returned: The insert_menuitem() function does not return a value.


ΓòÉΓòÉΓòÉ 14.11.7. menu_functions ΓòÉΓòÉΓòÉ

menu_functions.

Purpose: Lists the functions to execute when a menu item is selected.

____________

Syntax: menu_functions

____________

Description: The menu_functions variable contains a list of the functions to
execute when a menu item is selected.  It is your responsibility to enter this
information when you create a menu. Control structures, examples To run
gui_command when the menu with the command ID of 6 is selected, you would
enter:

menu_functions[6] = "gui_command"


ΓòÉΓòÉΓòÉ 14.11.8. menu_info() ΓòÉΓòÉΓòÉ

menu_info()    Primitive

Purpose: Retrieves information about a menu.

____________

Syntax: any menu_info(long menuid,short flags,opt short itemid)

____________

Description: The menu_info() function retrieved information about a menu
depending on the flags specified.

The menuid argument contains the menu id that information is requested for.  If
menuid is not 0 then the argument must contain a value that was returned from
create_menu().

The flags argument contains one of the following:


  MI_CHECKED   - gets the checked/unchecked state of the menu
item.

  MI_ENABLED   - determines whether to menu item is enabled or

          disabled.

  MI_ITEMCOUNT  - calculates the number of menu items in the
menu.

  MI_ITEMTEXT   - retrieves the text associated with the menu
item.

  MI_MENUHANDLE  - retrieves the menu id of a submenu.

The itemid argument contains the menu item id that is used to retrieve the
desired information.

____________

Value returned: The menu_info() function returns the following values:


  If menuid == 0 then
  returns the menuid of the main menu.

  If menuid != 0 and flags == MI_CHECKED then
  returns 1 if itemid is selected, otherwise 0.

  If menuid != 0 and flags == MI_ENABLED then
  returns 1 if itemid is enabled, otherwise 0.

  If menuid != 0 and flags == MI_ITEMCOUNT then
  returns number of items contained in menuid.

  If menuid != 0 and flags == MI_MENUHANDLE then
  returns the submenu menuid


ΓòÉΓòÉΓòÉ 14.11.9. modify_menuitem() ΓòÉΓòÉΓòÉ

modify_menuitem()   Primitive

Purpose: Modifies attributes of a particular menu item.

____________

Syntax: void modify_menuitem(long  menuid, short itemid, short flag, opt any
info)

____________

Description: The modify_menuitem() modifies the attributes of the menuid menu
item. The following attributes of the menu can be modified:

- Check or uncheck menu item
- Enable or disable menu item
- Item text of menu item
- Help text of menu item
- Macro id associated with the menu item

The menuid argument contains the id of the menu which contains the menu item to
be modified.  menuid must be a value returned from the create_menu() function.

The itemid argument contains the id of the menu item that is going to be
modified.

The flag argument contains the operation to be performed on the menu item. The
flag argument must contain one of the following values:

MI_CHECKED     - sets or unsets a check mark next to the menu item.

MI_ENABLED     - enables or disables the menu item.

MI_ITEMTEXT    - sets the menu text for the menu item.

MI_HELPTEXT    - sets the help text for the menu item.

MI_FUNCTIONID  - sets the macro id associated with the menu item.
The info parameters contains flag specific information.  The followings values
are valid for a given flag:

  flag      info
  ----------   ---------
  MI_CHECKED   0 - uncheck
         1 - check

  MI_ENABLED   0 - disable
         1 - enable

  MI_ITEMTEXT   String containing item text

  MI_HELPTEXT   String containing help text

  MI_FUNCTIONID  Macroid of function

____________

Value returned: The modify_menuitem() function does not return a value.


ΓòÉΓòÉΓòÉ 14.11.10. show_popup() ΓòÉΓòÉΓòÉ

show_popup()   Primitive

Purpose: Displays a popup menu

____________

Syntax: void show_popup(long menuid)

____________

Description: The show_popup() function displays a popup menu.

The menuid argument contains the id of the menu that is to be displayed as a
popup menu.  The menuid argument must be a value returned from the
create_menu() function call.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.11.11. user_menu() ΓòÉΓòÉΓòÉ

user_menu()   PEL

Purpose:  Entry point for user defined help.

____________

Syntax:   void user_menu(menuhndl main_menu )

____________

Arguments:

o main_menu - handle of the main menu

Description: The user_menu() function is the entry point for user defined
menus.  Menus are added using the append_menuitem() function.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.12. Miscellaneous ΓòÉΓòÉΓòÉ

abs()
          Find the absolute value of an integer.
add_compiler()
          Add a new compiler to the list of supported compilers.
change_footer_font()
          To change the printing footer font.
change_header_font()
          To change the printing header font.
change_menu()
          To attach a menu to a window.
change_print_font()
          To change the printing font.
compile_buffer()
          Compiles the current buffer.
debug()
          Invokes the debugging package.
delete_line_command()
          Delete a line command from the line command list.
execute_on_window()
          Execute a function in a window other than the current window.
max()
          Find the maximum of two integer values.
min()
          Find the minimum of two integer values.
minimize_and_save()
          To write all buffers and minimize the editor.
play()
          Play music from the speaker.
print()
          Send text to the standard output device a la AWK.
print_select_dialog()
          Allows selecting a printer
process_command_line()
          Interprets the editor command line arguments and options.
restore_position()
          Move to a previously saved position in the buffer.
save_position()
          Note the current buffer position in special stack.
startup()
          Controls editor initialization process.
symbol_under_cursor()
          To return the word under the cursor.
update_config_section()
          To update a section of the config file
update_current_caption()
          To update the caption(title) of the current window.
update_line_command()
          Redraw the line number area in ISPF mode.
write_state_file()
          Save the state sections of the config file.


ΓòÉΓòÉΓòÉ 14.12.1. abs() ΓòÉΓòÉΓòÉ

abs()   PEL

Purpose: Find the absolute value of an integer.

____________

Syntax: int abs(int value)

____________

Description: The abs() function calculates the arithmetic absolute value of the
argument value.

____________

Value returned:

If value <  0, abs() returns (-1) * value.

If value >= 0, abs() returns value.


ΓòÉΓòÉΓòÉ 14.12.2. add_compiler() ΓòÉΓòÉΓòÉ

add_compiler()   PEL

Purpose: Add a new compiler to the list of supported compilers.

____________

Syntax:  void add_compiler(str ext_list, str cmd_line [, str err_name ]

____________

Description: The add_compiler() function adds support for a compiler for which
support is not built-in.  If the need for the added compiler is on-going, the
add_compiler() call should be placed in the configuration file or local_setup()
function so that this information will be retained from one editor session to
the next.

The first argument, ext_list, is a list of the filename extensions used by the
new compiler.  Elements of the list may be separated by spaces or commas.  The
principle extension appears first in this list.  Other extensions in the list
signify header files or other "include" files that are not normally named on
the compiler command line.

The second argument, cmd_line, is used to define the command line normally used
for compiling these files.  Remember that this command line is presented to the
user for editing just before execution, so it is not necessary that this
command line fit all anticipated situations. Several built-in macros have been
defined for use in the cmd_line string.  These allow you to refer to the source
file name and parts of the source file name in general terms.  These macros are
as follows:

MACRO REPLACEMENT VALUE
$< complete name of the source file.
$r root (basename) of the source file.
$e extension of source file, excluding "."
$p drive and path of source file (ends in "\")

The optional third argument, err_name, determines which predefined rule set to
use in interpreting the error listing file and names the file in which any
errors generated during a compile will be captured.  If this argument is
omitted or null, the generic rule set is used and the source file's extension
is used as the error file's basename (root).

The correct rule set allows the editor to place the cursor at the offending
position in the proper source file.  The defined rule sets are identified by
labels which may be used as the err_name argument. These include:  "generic",
"pel", "TurboC", "Clipper", and "none".  Character case is not significant when
specifying these strings.  If the err_name argument does not match one of these
labels, the generic rules are used and the err_name string is used only as a
basename for the error listing file.

The "generic" rule set accommodates the error listing format used by Microsoft
compilers, Lattice C, Borland's Turbo Pascal, and many others.  The "pel" rule
set is designed for use with the editor function library source files.
"TurboC" identifies the rules for use with Borland's Turbo C and "Clipper"
identifies the dBase dialect error format rules.  If no rule set is to be used,
the label "none" is used. In this case, captured errors are displayed in a
window rather than at their position within the source file.

Compiler support added with the add_compiler() function takes precedence over
rules previously defined for the specified extension.  For example, there is
built-in support for files with the extension ".C".  If you specify the .C
extension in the ext_list argument to an add_compiler() call, the built-in
rules for that extension are superseded.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.3. change_footer_font() ΓòÉΓòÉΓòÉ

change_footer_font()   Primitive

Purpose:  To change the printing footer font.

____________

Syntax:   change_footer_font( str name, long width, long height, long
attributes )

____________

Arguments:

o name - the name of the new footer font
o width - the width of the new footer font
o height - the height of the new footer font
o attributes - the attributes of the new footer font

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.12.4. change_header_font() ΓòÉΓòÉΓòÉ

change_header_font()   Primitive

Purpose:  To change the printing header font.

____________

Syntax:   change_header_font( str name, long width, long height, long
attributes )

____________

Arguments:

o name - the name of the new header font
o width - the width of the new header font
o height - the height of the new header font
o attributes - the attributes of the new header font

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.12.5. change_menu() ΓòÉΓòÉΓòÉ

change_menu()   Primitive

Purpose:  To attach a menu to a window.

____________

Syntax:   change_menu( long mh, [long parent] )

____________

Arguments:

o mh - menu to change to
o parent - optional, parent of the menu

Description:

____________

Value returned: Handle of the menu replaced, 0 if none there


ΓòÉΓòÉΓòÉ 14.12.6. change_print_font() ΓòÉΓòÉΓòÉ

change_print_font()   Primitive

Purpose:  To change the printing font.

____________

Syntax:   change_print_font( str name, long width, long height, long attributes
)

____________

Arguments:

o name - the name of the new printing font
o width - the width of the new printing font
o height - the height of the new printing font
o attributes - the attributes of the new printing font

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.12.7. compile_buffer() ΓòÉΓòÉΓòÉ

compile_buffer()   PEL

Purpose: Compiles the current buffer.

____________

Syntax:  void compile_buffer([bool list_all], [bool background], [bool
disable_dialog], [string input_file], [string source_file])

____________

Arguments:

list_all - a flag which causes all output from the compiler to be placed into
the dialog.  If list_all is not provided, the value of list_all_output is used.

background - a flag which causes the compiler to be executed in the background.
If you do not set this flag, it defaults to TRUE.

disable_dialog - a flag which causes the compiler to be executed in the
background.  If you do not set this flag, it defaults to TRUE.

input_file - the name of a file to be used as input to the compiler.  If the
first character is -, >, or < a temporary file containing the rest of the
characters is created and used.

source_file - the name of the source file to compile.  If omitted, the
current_buffer is used.

____________

Description: The compile_buffer() function attempts to compile the current
buffer using rules associated with the file type.  The current buffer is saved
to disk to ensure that the file the compiler works on reflects all changes.
The buffer's filename extension is scrutinized to determine which compiler will
be used and then that compiler is called.

The editor has a number of built-in rules that determine what command line is
issued for a file bearing a certain extension.  If the built-in rules do not
suit your particular situation, you may use the add_compiler() function to
extend or modify the built-in rules.

____________

Value returned:

The status returned by the compiler is returned.

____________

See also:  add_compiler(), display_error_file_key(), goto_next_error()


ΓòÉΓòÉΓòÉ 14.12.8. debug() ΓòÉΓòÉΓòÉ

debug()   PEL

Purpose: Invokes the debugging package.

____________

Syntax:  void debug()

____________

 Description: The debug() function provides a convenient method of finding out
what the extension language functions you have written are doing when they
aren't doing what you expected.  This function uses a number of low-level
functions to allow you to set break points, step through your code, and trace
into functions or step over them.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.9. delete_line_command() ΓòÉΓòÉΓòÉ

delete_line_command   Primitive

Purpose:  Delete a line command from the line command list.

____________

Syntax:   void delete_line_command([int num])

____________

Arguments:

o num - linenumber of the command to delete

Description: The delete_line_command() deletes the command from the specified
line.  If no line is specified, all commands are deleted form the current view.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.12.10. execute_on_window() ΓòÉΓòÉΓòÉ

execute_on_window   Primitive

Purpose:  Execute a function in a window other than the current window.

____________

Syntax:   any execute_on_window(str funcname, long winid)

____________

Arguments:

o funcname - name of the function to execute
o winid - id of the window in which the function will be executed

Description: The execute_on_window() function executes the given function in
the specified window.  This prevents the user from having to switch to that
window in order to perform the function.

____________

Value returned: Return value from the function call, or 0 if failure.


ΓòÉΓòÉΓòÉ 14.12.11. max() ΓòÉΓòÉΓòÉ

max()   PEL

Purpose: Find the maximum of two integer values.

____________

Syntax: int max(int value1, int value2)

____________

Description: The max() function finds the parameter of with the largest value.
This value is then passed as the return value.

____________

Value returned:

If value1 <  value2, max() returns value2.

If value1 >= value2, max() returns value1.


ΓòÉΓòÉΓòÉ 14.12.12. min() ΓòÉΓòÉΓòÉ

min()   PEL

Purpose: Find the minimum of two integer values.

____________

Syntax: int min(int value1, int value2)

____________

Description: The min() function finds the parameter of with the smallest value.
This value is then passed as the return value.

____________

Value returned:

If value1 <  value2, min() returns value1.

If value1 >= value2, min() returns value2.


ΓòÉΓòÉΓòÉ 14.12.13. minimize_and_save() ΓòÉΓòÉΓòÉ

minimize_and_save()   PEL

Purpose:  To write all buffers and minimize the editor.

____________

Syntax:   minimize_and_save()

____________

Arguments:  none

Description: Because it is more efficient to leave the editor running all of
the time instead of quiting and restarting it every time you want to edit a
file, this function has been provided to save all modified buffers and minimize
the editor. Simply call this function when you would normally quit the editor,
and it will behave as you would expect, except that the editor will still be
running in the background.  This function is frequently assigned to the
standard "quit" key of the user's emulation and provides a good transition for
those users who find it hard to break the habit of quiting the editor when done
editing a file.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.12.14. play() ΓòÉΓòÉΓòÉ

play()   Primitive

Purpose: Play music from the speaker.

____________

Syntax: void play(str string)

____________

Description: The play() function produces musical notes to be emitted from the
speaker, based on instructions contained in the string argument.  The
instructions in the string must conform to a special "Play" language.  This
language is similar to that used by the Microsoft Basic PLAY statement, and is
described below.

The play() function is capable of playing 84 different notes, comprising 7
octaves.  These notes may be specified by number ( 1-84 ) or by octave and
letter ( A-G ).  Octaves are numbered from 0 to 6.  In addition, duration and
tempo may also be indicated.

Specifying Notes

Notes may be specified by placing some combination of the letters A through G
into the s argument or by inserting the letter N immediately followed by the
note number.  Note letters A to G may be followed by either # or + to indicate
sharp, or by - to indicate flat.  Note numbers range from 1 to 84, with 1
representing the lowest note and 84 representing the highest.

Octaves

When specifying notes by letter, stating the octave is usually desirable.
Initially, the octave is set by inserting the letter o in the play string
followed immediately by the octave number ( 0-6 ). Later in the string you may
wish to change octaves by inserting another o instruction, or by using the < or
> instruction.

The < and > instructions shift the octave down and up respectively for the
notes that follow.  These instructions shift the effective octave a single
octave per instruction and have no effect if the shift would advance the octave
higher than 6 or lower than 0.

Rests

Rests may be played by specifying note 0 in conjunction with the N instruction
( N0 ), or by using the pause instruction.  The pause instruction is the letter
P followed by a number in the range of 1 to 64 to specify the length of the
pause ( e.g., P2 ).  A value of 1 signifies a rest equivalent to a whole note,
4 a quarter note, 8 an eighth note and so on.  The higher the number, the
shorter the rest.

Duration and Tempo

Just as the length of a pause may be set, the duration and tempo of notes may
also be specified. The L instruction determines the relative length of each
note that follows it.  It is immediately followed by a number indicating the
value of the notes ( e.g., L4 ).  This number is in the same range and has the
same meaning as the number following the pause instruction, described above. A
dot placed after the note letter has the same effect on duration as a dot
placed after a note in a musical score:  the duration of the note is increased
by half.

The actual time allotted to notes is determined by the tempo instruction.  The
tempo instruction takes the form of a T followed by a number.  The number
specifies the number of quarter notes per minute. If the T instruction is not
specified, a value of 120 quarter notes per minute is used.  A range of values
from 32 to 255 may be specified.

Style

The musical style of the notes may also be set, which also affects the
duration.  The style instruction is the letter M followed by either an N, L or
S for Normal Legato or Staccato, respectively.  The default setting is
equivalent to MN, which causes notes to be sustained for seven eighths of the
interval indicated by the length ( L ) instruction.  The ML instruction causes
notes to be sustained for the full interval, and MS instruction for three
fourths the interval.

Notation  Description
A-G       Notes within the current octave.
Nn        Note n within the range 1 to 84.
N0        Rest.
#,+       Note postfix modifiers indicating sharp.
-         Note postfix modifier indicating flat.
<         Set octave one octave lower.
>         Set octave one octave higher.
On        Set octave to octave n in range 0 to 6.
Pn        Pause for n interval in range 1 to 64.
Ln        Sustain notes for n interval in range 1 to 64.
┬╖         Note Postfix modifier indicating dotted note.
Tn        Set tempo to n quarter notes per minute.
MN        Set style to Normal (sustain 7/8ths interval).
ML        Set style to Legato (sustain entire interval).
MN        Set style to Staccato (sustain 3/4ths interval).

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.15. print() ΓòÉΓòÉΓòÉ

print()   Primitive

Purpose: Send text to the standard output device a la AWK.

____________

Syntax: void print(any expr [, any expr...])

____________

Description: The print() function is an AWK statement.  The default action for
print is to send the string equivalent of any expressions given as arguments to
the Standard Output Device.  The output always ends with a new-line sequence.

EXAMPLE

  print("All is well.")

Using print() in this manner usually has the effect of making a mess of the
editor's display.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.16. print_select_dialog() ΓòÉΓòÉΓòÉ

print_select_dialog()   Primitive

Purpose: Allows selecting a printer

____________

Syntax: void print_select_dialog()

____________

Description: The print_select_dialog() function allows the user to select a
default printer.

____________

Value returned: This function does not return any value.


ΓòÉΓòÉΓòÉ 14.12.17. process_command_line() ΓòÉΓòÉΓòÉ

process_command_line()   PEL

Purpose: Interprets the editor command line arguments and options.

____________

Syntax: void process_command_line()

____________

Description: The process_command_line() function performs the start-up task of
interpreting flags and filenames specified on the command line.  The
interpretation and handling of the command line may be modified by changing
this function.  The function is supplied in the file NUCLEUS.PEL.  This
function is called by startup().

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.18. restore_position() ΓòÉΓòÉΓòÉ

restore_position()

Purpose: Move to a previously saved position in the buffer.

____________

Syntax: int restore_position([int go_there])

____________

Description: The restore_position() function "pops" the most recently saved
buffer position from the position stack it shares with the save_position()
function. The stack operates on a last-in, first-out basis. If the go_there
argument represents a non-zero value the cursor moves to the saved position.
If the go_there argument is omitted or is zero, the saved position is removed
from the stack and not used.

____________

Value returned: This function returns no useful value.

____________

See also:   save_position()


ΓòÉΓòÉΓòÉ 14.12.19. save_position() ΓòÉΓòÉΓòÉ

save_position()   Primitive

Purpose: Note the current buffer position in special stack.

____________

Syntax: int save_position()

____________

Description: The save_position() function stores the current position within
the buffer on the position stack it shares with the restore_position()
function.  The stack operates on a last-in, first-out basis.

This differs from the drop_anchor() function primarily in that no block of text
is highlighted.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.20. startup() ΓòÉΓòÉΓòÉ

startup()   PEL

Purpose: Controls editor initialization process.

____________

Syntax: void startup()

____________

Description: The startup() function performs a number of tasks associated with
initialization of the editor. Among these tasks are:  reading and processing
the configuration file, performing "local" setup, interpreting the command line
and assigning an initial emulation mode (not necessarily in that order).  This
is done primarily by calling other initialization functions described elsewhere
in this manual:  process_command_line() and local_setup().  The startup()
function is found in the supplied source file STARTUP.PEL.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.12.21. symbol_under_cursor() ΓòÉΓòÉΓòÉ

symbol_under_cursor()   PEL

Purpose:  To return the word under the cursor.

____________

Syntax:   symbol_under_cursor( [regex symbol_regex] )

____________

Arguments:

o symbol_regex  - optional definition of a word

Description: This function returns the word at the current cursor location. It
is used in many functions that operate on search patterns, and provides a
simple way to save keystrokes.

____________

Value returned:  The word at the current cursor location as a string


ΓòÉΓòÉΓòÉ 14.12.22. update_config_section() ΓòÉΓòÉΓòÉ

update_config_section()   PEL

Purpose:  To update a section of the config file

____________

Syntax:   update_config_section( str section_name, array data_array )

____________

Arguments:

o section_name  - the section heading to update, starting and ending with '$'
o data_array   - an array containing the lines you wish to put in the config
  section

Description: This function has been provided to update a section of the
configuration file.  The previous data in the section will be deleted, and the
elements of the data array will be inserted into the section on separate lines.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.12.23. update_current_caption() ΓòÉΓòÉΓòÉ

update_current_caption()   Primitive

Purpose:  To update the caption(title) of the current window.

____________

Syntax:   update_current_caption()

____________

Arguments:  none

Description: Under most circumstances, the caption of each text window is
updated when appropriate.  When the buffer_filename is changed, however, the
caption currently needs to be updated manually through this function.

____________

Value returned: TRUE  -  current window is valid, caption updated FALSE -
current window is invalid


ΓòÉΓòÉΓòÉ 14.12.24. update_line_command() ΓòÉΓòÉΓòÉ

update_line_command   Primitive

Purpose:  Redraw the line number area in ISPF mode.

____________

Syntax:   void update_line_command([int num])

____________

Arguments:

o num - line to be redrawn

Description: The update_line_command() function redraws the line command area
when in ISPF mode.  If the optional parameter is supplied, it is the only line
redrawn.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.12.25. write_state_file() ΓòÉΓòÉΓòÉ

write_state_file()   PEL

Purpose:  Save the state sections of the config file.

____________

Syntax:   void write_state_file()

____________

Arguments: none.

Description: The write_state_file() function saves the sections of the config
file that record the state of the editor.  This function is usually attached to
EVENT.EXIT_EDITOR.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13. Motion ΓòÉΓòÉΓòÉ

The variables and functions in the Motion category provide a variety of
controls over cursor action and cursor position.  The cursor position and the
current location within the buffer are synonymous.  Each buffer you create has
a current location.  The cursor is located at the current location of the
active buffer.  The variables describe the limits of where the cursor may go,
and how scrolling operates.  The functions move the cursor to positions
relative to its current position or relative to the window or screen.

Virtual Space

One of the limits described by a variable, and observed by many of the
functions in this category, is whether the cursor may move to locations in the
buffer where there are no characters.  For example, space may be visible within
the window beyond the end of the line, or where a tab pushes the text following
to the next tab-stop.

This space that is visible in the window but not represented by characters in
the buffer is known variously as "the ozone" or "virtual space".  Many cursor
motion functions will operate somewhat differently, depending on whether you
have enabled movements into virtual space.

Goto vs Scroll

There are several functions whose names differ only in that one begins with
scroll_ and the other begins with goto_ ( e.g., goto_window_middle() and scroll
_window_middle() ).  The functions that begin with goto_ primarily change the
cursor position.  Many do not change what portion of the buffer the editor
shows in the window.  Those that do, only do so as required as a result of
changing the cursor position.

In contrast, the primary task of the scroll_ functions is to shift the text
viewed in the window.  If the cursor position changes, it is a secondary
effect.

center_cursor()
          This function scrolls the current line to the center of the current
          window
down()
          Move the cursor by lines toward the bottom of buffer.
goto_bol()
          Moves the cursor to the beginning of the current line.
goto_bolc()
          Move cursor to the begining of the line command area.
goto_bookmark()
          Moves to non-local bookmarks.
goto_bookmark_key()
          Move to single bookmark or prompt if more than one.
goto_buffer_bottom()
          Moves the cursor to the end of the current buffer.
goto_buffer_offset()
          Move the cursor to a specified buffer position.
goto_buffer_top()
          Moves the cursor to the beginning of the buffer.
goto_eol()
          Moves the cursor to the end of the current line.
goto_line()
          Go to the first column of a line specified by number.
goto_line_key()
          Prompts for and moves to a specified line.
goto_line_or_mark()
          Prompts for line or mark number.
goto_mark()
          Move cursor to position indicated by a bookmark.
goto_next_tab()
          Move the cursor to the next tab stop position.
goto_old_line()
          Go to line when only its original line number is known.
goto_pos()
          Move to a specific line and column within the buffer.
goto_prev_tab()
          Move the cursor to the previous tab stop position.
goto_window_bottom()
          Moves cursor to the text in the last line of the window.
goto_window_left()
          Moves cursor to text at the left edge of the window.
goto_window_middle()
          Moves cursor to text in the middle line of the window.
goto_window_right()
          Moves cursor to text at the right edge of the window.
goto_window_top()
          Moves cursor to the text in the first line of the window.
left()
          Move cursor to the left on the line.
next_char()
          Move cursor to a subsequent character in the buffer.
next_line()
          Moves cursor to the start of text on subsequent line.
next_paragraph()
          Move forward in the buffer to the begining of the next paragraph
next_section()
          Move forward in the buffer to the begining of the next section
next_sentence()
          Moves the cursor to beginning of next sentence.
next_word()
          Moves cursor to the first character of following word.
page_down()
          Move the cursor ahead in the buffer one page.
page_up()
          Move the cursor backward in the buffer one page.
prev_char()
          Move cursor to a previous character in the buffer.
prev_line()
          Moves cursor to the start of text on previous line.
prev_paragraph()
          Move backward in the buffer to the begining of the previous paragraph
prev_section()
          Move backward in the buffer to the begining of the previous section
prev_sentence()
          Moves cursor to beginning of previous sentence.
prev_word()
          Moves cursor to the first character of previous word.
right()
          Move cursor to the right on the line.
rs_down()
          To provide a more convenient down() for real space only movement.
rs_page_down()
          To provide a more convenient page_down() for real space only
          movement.
rs_page_up()
          To provide a more convenient page_up() for real space only movement.
rs_up()
          To provide a more convenient up() for real space only movement.
scroll_down_1()
          Scroll one line toward the end of the buffer.
scroll_down_half()
          Scrolls toward end of buffer by half a window.
scroll_horizontal()
          Move text right or left while cursor maintains position.
scroll_left_1()
          Scroll toward start of line by one column.
scroll_or_pan()
          Tells condition of Scroll Lock key.
scroll_up_half()
          Scrolls toward start of buffer by half a window.
scroll_vertical()
          Move text up or down while cursor maintains position.
scroll_window_bottom()
          Scroll cursor line to position relative to window bottom
scroll_window_middle()
          Scroll cursor line to position relative to window center.
scroll_window_top()
          Scroll cursor line to position relative window top
skip_whitespace()
          Move cursor to beginning of text on current line.
up()
          Move the cursor by lines toward the top of the buffer.
up_whitespace()
          Move cursor up to the begining of whitespace.


ΓòÉΓòÉΓòÉ 14.13.1. center_cursor() ΓòÉΓòÉΓòÉ

center_cursor()   PEL

Purpose:  This function scrolls the current line to the center of the current
window

____________

Syntax:   center_cursor()

____________

Arguments:  none

Description:

____________

Value returned:   none


ΓòÉΓòÉΓòÉ 14.13.2. down() ΓòÉΓòÉΓòÉ

down()   Primitive

Purpose: Move the cursor by lines toward the bottom of buffer.

____________

Syntax:  int down([int lines])

____________

Description: The down() function advances the cursor the number of lines found
in the lines argument.  If the lines argument is not supplied, 1 line is
assumed.

Negative values for lines are allowed and result in the cursor moving in the
opposite direction.  In other words, calling down() with -3 as the argument is
the as calling up() with 3 as the argument.

The column position of the cursor resulting from a call to down() may be
affected by the buffer_flags variable described above. If movement into VIRTUAL
SPACE is allowed, the cursor always maintains the same column position at its
new line location.

If movements into VIRTUAL SPACE are disallowed the column position may change.
When the down() function would position the cursor beyond the end-of-line, it
moves to the nearest column on the new line location which contains a
character.  If down() moves the cursor into a tab, the cursor always moves to
the beginning of the tab.

If there are fewer lines remaining between the cursor position and the end of
the buffer than the lines argument specifies, the cursor is moved to the last
line of the buffer.  A short beep is issued from the speaker if there are no
lines between the cursor and the end of the buffer.

____________

Value returned:

The down() function returns a non-zero (TRUE) value to indicate that the cursor
has been moved.  If the cursor does not move as a result of this function, a
zero or FALSE value is returned.


ΓòÉΓòÉΓòÉ 14.13.3. goto_bol() ΓòÉΓòÉΓòÉ

goto_bol()   Primitive

Purpose: Moves the cursor to the beginning of the current line.

____________

Syntax:  int goto_bol()

____________

Description: The goto_bol() function moves the cursor to the beginning of the
line it currently occupies.

____________

Value returned:

The value returned by the goto_bol() function is non-zero (TRUE) if the cursor
was moved.  If the cursor was already at the beginning of the line a zero
(FALSE) value is returned.


ΓòÉΓòÉΓòÉ 14.13.4. goto_bolc() ΓòÉΓòÉΓòÉ

goto_bolc   Primitive

Purpose:  Move cursor to the begining of the line command area.

____________

Syntax:   void goto_bolc()

____________

Arguments: none.

Description: The goto_bolc() function moves the cursor to the begining of the
line number area.  This function is valid only in the ISPF emulation mode.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.5. goto_bookmark() ΓòÉΓòÉΓòÉ

goto_bookmark()   PEL

Purpose: Moves to non-local bookmarks.

____________

Syntax:  void goto_bookmark([int n])

____________

Description: The goto_bookmark() function is an enhanced version of the
goto_mark() function.  The function goto_mark() requires that the mark be
defined in the current buffer.  If the function place_bookmark() is used to
define the bookmark, goto_bookmark() can move to it regardless of the buffer in
which it was defined.  In addition, this function prompts for the mark number
if not supplied.

There is no limit to the number of bookmarks you can place.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.6. goto_bookmark_key() ΓòÉΓòÉΓòÉ

goto_bookmark_key()   PEL

Purpose: Move to single bookmark or prompt if more than one.

____________

Syntax:  void goto_bookmark_key()

____________

Description: The goto_bookmark_key() function is an enhanced version of
goto_bookmark().  If only one bookmark is defined, the cursor is moved without
prompting.  If more than one bookmark is defined, the available bookmark values
are displayed on the prompt line.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.7. goto_buffer_bottom() ΓòÉΓòÉΓòÉ

goto_buffer_bottom()   Primitive

Purpose: Moves the cursor to the end of the current buffer.

____________

Syntax:  int goto_buffer_bottom()

____________

Description: The goto_buffer_bottom() function moves the cursor to the position
immediately following the last character in the current buffer.

____________

Value returned:

The goto_buffer_bottom() function returns a non-zero (TRUE) value to indicate
that the cursor has been moved.  If the cursor does not move as a result of
this function, a zero or FALSE value is returned.


ΓòÉΓòÉΓòÉ 14.13.8. goto_buffer_offset() ΓòÉΓòÉΓòÉ

goto_buffer_offset()   Primitive

Purpose: Move the cursor to a specified buffer position.

____________

Syntax:  void goto_buffer_offset(int num)

____________

Description: The goto_buffer_offset() function places the cursor at the
position in the buffer dictated by the num argument.  The num argument
represents the number of characters which are to precede the cursor at its new
position.

If num specifies an offset greater than the contents of the buffer, the cursor
position is moved to the end of the buffer. Negative values for num move the
cursor to the beginning of the buffer.

____________

Value returned:

No useful value is returned by this function.

____________

See also:  buffer_offset, buffer_size, buffer_last_line


ΓòÉΓòÉΓòÉ 14.13.9. goto_buffer_top() ΓòÉΓòÉΓòÉ

goto_buffer_top()   Primitive

Purpose: Moves the cursor to the beginning of the buffer.

____________

Syntax:  int goto_buffer_top()

____________

Description: The goto_buffer_top() function moves the cursor to the first
character in the current buffer regardless of its previous location.

____________

Value returned:

The goto_buffer_top() function returns a non-zero (TRUE) value if the cursor
was moved.  A zero or FALSE value is returned if the cursor was already at the
beginning of the buffer.


ΓòÉΓòÉΓòÉ 14.13.10. goto_eol() ΓòÉΓòÉΓòÉ

goto_eol()   Primitive

Purpose: Moves the cursor to the end of the current line.

____________

Syntax:  int goto_eol()

____________

Description: The function goto_eol() moves the cursor to the end of the current
line.

____________

Value returned:

The goto_eol() function returns a non-zero (TRUE) value to indicate that the
cursor has been moved.  If the cursor does not move as a result of this
function, a zero or FALSE value is returned.


ΓòÉΓòÉΓòÉ 14.13.11. goto_line() ΓòÉΓòÉΓòÉ

goto_line()   PEL

Purpose: Go to the first column of a line specified by number.

____________

Syntax:  void goto_line(int num)

____________

Description: The goto_line() function moves the cursor to the first column of
the line indicated by the num argument.

The num argument must specify an integer with a positive value corresponding to
an existing line of text.  A number higher than any existing line moves the
cursor to the last line in the buffer.  If zero or a negative value is
specified for num, the cursor is moved to the beginning of the buffer.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.12. goto_line_key() ΓòÉΓòÉΓòÉ

goto_line_key()   PEL

Purpose: Prompts for and moves to a specified line.

____________

Syntax:  void goto_line_key()

____________

Description: The goto_line_key() function is a close relative of the
goto_line() function, suitable for assigning to a key.  It prompts for the
buffer line number where you wish to place the cursor and then goes there.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.13. goto_line_or_mark() ΓòÉΓòÉΓòÉ

goto_line_or_mark()   PEL

Purpose: Prompts for line or mark number.

____________

Syntax:  void goto_line_or_mark()

____________

Description: The goto_line_or_mark() function prompts for a line number at
which to place the cursor, but allows entering a mark number instead, if
preceded by "Mark #".  This makes it unnecessary to have separate key
assignments for each of these requirements.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.14. goto_mark() ΓòÉΓòÉΓòÉ

goto_mark()   Primitive

Purpose: Move cursor to position indicated by a bookmark.

____________

Syntax:  int goto_mark(int num)

____________

Description: The goto_mark() function moves the cursor to the column position
at the bookmark indicated by the num argument.  The num argument is a numeric
id given to a bookmark when it was created.  If num is not a valid bookmark,
the cursor is not moved.

This function may be used to move to the next bookmark in the buffer by using
the next_mark() function as the argument.

____________

Value returned:

The value returned by goto_mark() is non- zero (TRUE) if the named mark has
been previously defined.  If the mark has not been defined the value returned
is zero (FALSE).


ΓòÉΓòÉΓòÉ 14.13.15. goto_next_tab() ΓòÉΓòÉΓòÉ

goto_next_tab()   Primitive

Purpose: Move the cursor to the next tab stop position.

____________

Syntax:  int goto_next_tab()

____________

Description: The goto_next_tab() function moves the cursor to the tab stop
immediately following its current position. If the buffer_flags variable allows
movements into VIRTUAL SPACE, the tab stop may be beyond the end of the current
line of text.

If movements into VIRTUAL SPACE are not allowed, the cursor will move to the
first tab stop on the following line, when the current line does not extend to
the next tab stop.  If the cursor is already past the last tab stop in the
buffer, a short beep is emitted from the speaker and the cursor is not moved.

____________

Value returned:

The function goto_next_tab() returns the number of columns the cursor moved in
order to reach the next tab stop.  If the cursor does not move, the value
returned is zero.

____________

See also:  goto_prev_tab()


ΓòÉΓòÉΓòÉ 14.13.16. goto_old_line() ΓòÉΓòÉΓòÉ

goto_old_line()   Primitive

Purpose: Go to line when only its original line number is known.

____________

Syntax:  int goto_old_line(int num)

____________

Description: The function goto_old_line() moves the cursor to the new location
of the line denoted by the num argument.  As with goto_line(), the cursor moves
to the first column of that line.

The num argument is the number of the line at which the desired text was found
originally, or following the most recent save.  When a buffer is saved,
information about the previous locations of lines is lost.

If the line referred to by num has been deleted, the cursor moves to the
location from which the line was deleted.

____________

Value returned:

The goto_old_line() function returns a non- zero (TRUE) value if the cursor is
moved as a result of calling this function. Otherwise the function returns zero
(FALSE).


ΓòÉΓòÉΓòÉ 14.13.17. goto_pos() ΓòÉΓòÉΓòÉ

goto_pos()   Primitive

Purpose: Move to a specific line and column within the buffer.

____________

Syntax:  int goto_pos(int line, int column)

____________

Description: The goto_pos() function moves the cursor to the buffer line and
column number indicated in the arguments.  If the value of the line argument
exceeds the number of lines in the buffer, the cursor is placed on the last
line.

When movements into VIRTUAL SPACE are not allowed, two special conditions
apply:  If the value of the column argument exceeds the number of columns in
the line, the cursor is placed at the end of the line. In addition, if the
column location specified would place the cursor in the middle of a tab, the
cursor is instead positioned at the beginning of a tab.  When movements into
VIRTUAL SPACE are permitted, the cursor is placed at the indicated column,
regardless.

A zero value may be used for either argument and has special meaning.  When a
zero value is supplied as an argument, it specifies that the current line or
column number is to be preserved; depending on which argument is so specified.

If the line number specified is out of range, the editor will go to the last
line of the file.  If already on the last line, it will go to the end of the
line.

The following are two examples from common usage:   goto_pos(0,1)

This example moves the cursor to the first column of the line it presently
occupies.   goto_pos(1,0)

This example moves the cursor to the first line of the buffer, but the column
it occupies is unchanged.

If a negative value is supplied as an argument to this function, it is treated
as a value of 1.

____________

Value returned:

This function returns TRUE (a non-zero value) if the cursor moved.  It returns
FALSE (zero) if the cursor did not move.


ΓòÉΓòÉΓòÉ 14.13.18. goto_prev_tab() ΓòÉΓòÉΓòÉ

goto_prev_tab()   Primitive

Purpose: Move the cursor to the previous tab stop position.

____________

Syntax:  int goto_prev_tab()

____________

Description: The goto_prev_tab() function moves the cursor to the tab stop
immediately preceding its current position.

The cursor will move to the last tab stop within the preceding line, when the
current line does not contain a previous tab stop. If the cursor already
precedes the first tab stop in the buffer, a short beep is emitted from the
speaker and the cursor is not moved.

____________

Value returned:

The function goto_prev_tab() returns the number of columns the cursor moved in
order to reach the previous tab stop.  If the cursor does not move, the value
returned is zero (FALSE).

____________

See also:  goto_next_tab()


ΓòÉΓòÉΓòÉ 14.13.19. goto_window_bottom() ΓòÉΓòÉΓòÉ

goto_window_bottom()   PEL

Purpose: Moves cursor to the text in the last line of the window.

____________

Syntax:  void goto_window_bottom()

____________

Description: The goto_window_bottom() function moves the cursor to the last
visible line in the current window.  The column position is maintained when
possible.  When movements into VIRTUAL SPACE are not permitted the cursor may
be required to move left to the nearest real character.

____________

Value returned:

No useful value is returned by goto_window_bottom().


ΓòÉΓòÉΓòÉ 14.13.20. goto_window_left() ΓòÉΓòÉΓòÉ

goto_window_left()   PEL

Purpose: Moves cursor to text at the left edge of the window.

____________

Syntax:  void goto_window_left()

____________

Description: The goto_window_left() function moves the cursor to the first
position at the left edge or border of the window.  The cursor does not change
lines and text is not scrolled.  When movements into VIRTUAL SPACE are not
permitted, the cursor may be required to move away from the edge of the window
to the nearest real character.

____________

Value returned:

No useful value is returned by goto_window_left().


ΓòÉΓòÉΓòÉ 14.13.21. goto_window_middle() ΓòÉΓòÉΓòÉ

goto_window_middle()   PEL

Purpose: Moves cursor to text in the middle line of the window.

____________

Syntax:  void goto_window_middle()

____________

Description: The goto_window_middle() function moves the cursor to the middle
most line visible in the current window.  The column position is maintained
when possible.  When movements into VIRTUAL SPACE are not permitted the cursor
may be required to move left to the nearest real character.

____________

Value returned:

No useful value is returned by goto_window_middle().

goto_window_right()


ΓòÉΓòÉΓòÉ 14.13.22. goto_window_right() ΓòÉΓòÉΓòÉ

Purpose: Moves cursor to text at the right edge of the window.   PEL

____________

Syntax:  void goto_window_right()

____________

Description: The goto_window_right() function moves the cursor to the last
position at the right edge or border of the window.  The cursor does not change
lines and text is not scrolled.  When movements into VIRTUAL SPACE are not
permitted the cursor may be required to move away from the edge of the window
to the nearest real character.

____________

Value returned:

No useful value is returned by goto_window_right().


ΓòÉΓòÉΓòÉ 14.13.23. goto_window_top() ΓòÉΓòÉΓòÉ

goto_window_top()   PEL

Purpose: Moves cursor to the text in the first line of the window.

____________

Syntax:  void goto_window_top()

____________

Description: The goto_window_top() function moves the cursor to the first
visible line in the current window.  The column position is maintained when
possible.  When movements into VIRTUAL SPACE are not permitted the cursor may
be required to move left to the nearest real character.

____________

Value returned:

No useful value is returned by goto_window_top().


ΓòÉΓòÉΓòÉ 14.13.24. left() ΓòÉΓòÉΓòÉ

left()   Primitive

Purpose: Move cursor to the left on the line.

____________

Syntax: int left([int positions])

____________

Description: the left() function moves the cursor to the left by the number of
positions specified by the positions argument.  If the positions argument is
omitted, a value of one is assumed.

Depending on the value of the buffer_flags variable, positions are interpreted
as either columns or characters.  If movements into VIRTUAL SPACE are allowed,
the positions argument is interpreted as columns.  When movements into VIRTUAL
SPACE are disallowed, positions means characters; excluding end-of-line
sequences.

If the value of positions is greater than the number of columns or characters
between the cursor and the beginning of the line, the cursor moves only to the
beginning of the line. Negative values for positions are allowed and result in
the cursor moving in the opposite direction.  In other words, calling left()
with -3 as the argument is the as calling right() with 3 as the argument.

____________

Value returned: The left() function returns the actual number of columns or
characters traversed.  This will be the same number as the positions argument,
except when there are too few columns or characters between the cursor position
and the beginning of the buffer to execute the move completely.

____________

See also:   prev_char()


ΓòÉΓòÉΓòÉ 14.13.25. next_char() ΓòÉΓòÉΓòÉ

next_char()   Primitive

Purpose: Move cursor to a subsequent character in the buffer.

____________

Syntax: int next_char([int chars])

____________

Description: The next_char() function moves the cursor forward in the buffer by
the number of characters specified by the chars argument.  The end-of-line
sequence is always treated as a single character.  If the chars argument is
omitted, a value of one is assumed.

Negative values for chars are allowed and result in the cursor moving in the
opposite direction.  In other words, calling next_char() with -3 as the
argument is the as calling prev_char() with 3 as the argument.

This function is identical to the right()function described below, except that
it never causes the cursor to enter virtual space regardless of the setting of
the buffer_flags variable.

____________

Value returned: The next_char() function returns the actual number of
characters traversed.  This will be the same number as the chars argument,
except when there are too few columns or characters between the cursor position
and the end of the buffer to execute the move completely.

____________

See also:   right()


ΓòÉΓòÉΓòÉ 14.13.26. next_line() ΓòÉΓòÉΓòÉ

next_line()   PEL

Purpose: Moves cursor to the start of text on subsequent line.

____________

Syntax: void next_line()

____________

Description: The next_line() function moves the cursor to the subsequent line
in the buffer.  If there is any text on the line the cursor is placed on the
first character of this text.  Otherwise, the cursor is placed at the end of
the line.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.27. next_paragraph() ΓòÉΓòÉΓòÉ

next_paragraph()   PEL

Purpose:  Move forward in the buffer to the begining of the next paragraph

____________

Syntax:   void next_paragraph(int count)

____________

Arguments:

o count - number of paragraphs to move

Description: The next_paragraph() function moves the cursor to the begining of
the next paragraph.  If an argument is specified, the cursor is moved count
paragraphs.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.28. next_section() ΓòÉΓòÉΓòÉ

next_section()   PEL

Purpose:  Move forward in the buffer to the begining of the next section

____________

Syntax:   void next_section(int count)

____________

Arguments:

o count - number of sections to move

Description: The next_section() function moves the cursor to the begining of
the next section.  If an argument is specified, the cursor is moved count
sections.  A section is defined as a line begining with "{"

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.29. next_sentence() ΓòÉΓòÉΓòÉ

next_sentence()   PEL

Purpose: Moves the cursor to beginning of next sentence.

____________

Syntax: void next_sentence([int n])

____________

Description: The next_sentence() function advances the cursor to the first
non-whitespace character following a period and one or more spaces.  The n
argument may be used to indicate motions of more than one sentence.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.30. next_word() ΓòÉΓòÉΓòÉ

next_word()   PEL

Purpose: Moves cursor to the first character of following word.

____________

Syntax: int next_word([int count [, str regex]])

____________

Description: The next_word() function moves the cursor to the first character
of a word following the current position in the buffer.  The number of words
the cursor moves forward is determined by the value of the count argument.  If
this argument is not supplied the cursor moves forward one word.

The regex argument is a string containing a regular expression.  This string
defines what constitutes a word.  If this argument is omitted, a word is
defined as non-whitespace characters following one or more characters of
whitespace (spaces or tabs).

____________

Value returned: The value returned by next_word() is non-zero (TRUE) if the
cursor moved.  Otherwise a zero (FALSE) value is returned.


ΓòÉΓòÉΓòÉ 14.13.31. page_down() ΓòÉΓòÉΓòÉ

page_down()   Primitive

Purpose: Move the cursor ahead in the buffer one page.

____________

Syntax: int page_down([int pan])

____________

Description: The page_down() function advances the cursor position within the
buffer by a page.  A page is defined as the number of lines of text in the
window, less the value of the window_page_overlap variable.

If there is less than a page between the cursor position and the end of the
buffer, the last line of text is scrolled up to the cursor position.

The cursor may either scroll or pan as a result of the page_down() function.
When panning, the cursor attempts to maintain its position relative the window
regardless of the motion of text.  When scrolling, it attempts to maintain its
position within the buffer.

You may dictate whether this function causes the cursor to scroll or pan by
supplying the pan argument.  When pan is zero the cursor will scroll. Other
values for pan will cause the cursor to pan. If you do not supply the pan
argument, cursor action is determined by the condition of the scroll_means_pan
variable.

____________

Value returned: The value returned by the page_down() functions is the number
of lines actually scrolled.  If the cursor was already on the last line of the
buffer, a zero is returned.


ΓòÉΓòÉΓòÉ 14.13.32. page_up() ΓòÉΓòÉΓòÉ

page_up()   Primitive

Purpose: Move the cursor backward in the buffer one page.

____________

Syntax: int page_up([int pan])

____________

Description: The page_up() function moves the cursor position backward within
the buffer by a page.  A page is defined as the number of lines of text in the
window, less the value of the window_page_overlap variable.  If there is less
that a page of text between the current cursor position and the beginning of
the buffer, the cursor moves to the first line of text in the buffer.

The cursor may either scroll or pan as a result of the page_up() function.
When panning, the cursor attempts to maintain its position relative the window
regardless of the motion of text.  When scrolling, it attempts to maintain its
position within the buffer.

You may dictate whether this function causes the cursor to scroll or pan by
supplying the pan argument.  When pan is zero the cursor will scroll. Other
values for pan will cause the cursor to pan. If you do not supply the pan
argument, cursor action is determined by the condition of the scroll_means_pan
variable.

____________

Value returned: The value returned by the page_up() functions is the number of
lines actually scrolled.  If the cursor was already on the first line of the
buffer, a zero is returned.


ΓòÉΓòÉΓòÉ 14.13.33. prev_char() ΓòÉΓòÉΓòÉ

prev_char()   Primitive

Purpose: Move cursor to a previous character in the buffer.

____________

Syntax: int prev_char([int chars])

____________

Description: The prev_char() function moves the cursor backward in the buffer
by the number of characters specified by the chars argument.  The end-of-line
sequence always counts as a single character.  If the chars argument is
omitted, a value of one is assumed.

Negative values for chars are allowed and result in the cursor moving in the
opposite direction.  In other words, calling prev_char() with -3 as the
argument is the as calling next_char() with 3 as the argument.

This function is identical to the left() function, except that it never causes
the cursor to enter virtual space regardless of the setting of the buffer_flags
variable.

____________

Value returned: The prev_char() function returns the actual number of
characters traversed.  This will be the same number as the chars argument,
except when there are too few columns or characters between the cursor position
and the beginning of the buffer to execute the move completely.

____________

See also:   left()


ΓòÉΓòÉΓòÉ 14.13.34. prev_line() ΓòÉΓòÉΓòÉ

prev_line()   PEL

Purpose: Moves cursor to the start of text on previous line.

____________

Syntax: void prev_line()

____________

Description: The prev_line() function moves the cursor to the previous line in
the buffer.  If there is any text on the line the cursor is placed on the first
character of this text.  Otherwise, the cursor is placed at the end of the
line.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.35. prev_paragraph() ΓòÉΓòÉΓòÉ

prev_paragraph()   PEL

Purpose:  Move backward in the buffer to the begining of the previous paragraph

____________

Syntax:   void prev_paragraph(int count)

____________

Arguments:

o count - number of paragraphs to move

Description: The prev_paragraph() function moves the cursor to the begining of
the previous paragraph.  If an argument is specified, the cursor is moved count
paragraphs.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.36. prev_section() ΓòÉΓòÉΓòÉ

prev_section()   PEL

Purpose:  Move backward in the buffer to the begining of the previous section

____________

Syntax:   void prev_section(int count)

____________

Arguments:

o count - number of sections to move

Description: The prev_section() function moves the cursor to the begining of
the previous section.  If an argument is specified, the cursor is moved count
sections.  A section is defined as a line begining with "{"

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.37. prev_sentence() ΓòÉΓòÉΓòÉ

prev_sentence()   PEL

Purpose: Moves cursor to beginning of previous sentence.

____________

Syntax: void prev_sentence([int n])

____________

Description: The prev_sentence() function moves the cursor backward to the
first non-whitespace character following a period and one or more spaces.  The
n argument may be used to indicate motions of more than one sentence.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.38. prev_word() ΓòÉΓòÉΓòÉ

prev_word()   PEL

Purpose: Moves cursor to the first character of previous word.

____________

Syntax: int prev_word([int count [, str regex]])

____________

Description: The prev_word() function moves the cursor to the first character
of a word preceding the current position in the buffer.  When the cursor is
located within a word, the prev_word() function moves it to the beginning of
that word.

The number of words the cursor moves backward is determined by the value of the
count argument.  If this argument is not supplied the cursor moves backward one
word.

The regex argument is a string containing a regular expression.  This string
defines what constitutes a word.  If this argument is omitted, a word is
defined as non-whitespace characters following one or more characters of
whitespace (spaces or tabs).

____________

Value returned: The value returned by prev_word() is non-zero (TRUE) if the
cursor moved.  Otherwise a zero (FALSE) value is returned.


ΓòÉΓòÉΓòÉ 14.13.39. right() ΓòÉΓòÉΓòÉ

right()   Primitive

Purpose: Move cursor to the right on the line.

____________

Syntax: int right([int positions])

____________

Description: The right() function moves the cursor to the right by the number
of positions specified by the positions argument.  If the positions argument is
omitted, a value of one is assumed.

Depending on the value of the buffer_flags variable, positions are interpreted
as either columns or characters.  If movements into virtual space are allowed,
the positions argument is interpreted as columns.  The right() function always
moves the cursor to the right the number of characters indicated.  It does not
move the cursor to the following line.

When movements into virtual space are disallowed, positions means characters;
excluding end-of-line sequences.  The right() function then follows the text in
the buffer.  If the value of positions is greater than the number of columns or
characters between the cursor and the end-of-line, the cursor is moved to the
beginning of text in the following line.  The cursor is then moved to the right
any additional positions.

Negative values for positions are allowed and result in the cursor moving in
the opposite direction.  In other words, calling right() with -3 as the
argument is the as calling left() with 3 as the argument.

____________

Value returned: The right() function returns the actual number of columns or
characters traversed.  This will be the same number as the positions argument,
except when movements into virtual space are disabled and there are too few
characters between the cursor position and the end of the buffer to execute the
move completely.

____________

See also:   next_char()


ΓòÉΓòÉΓòÉ 14.13.40. rs_down() ΓòÉΓòÉΓòÉ

rs_down()   PEL

Purpose:  To provide a more convenient down() for real space only movement.

____________

Syntax:   rs_down()

____________

Arguments:  none

Description: This function provides a more convenient way of moving down when
the cursor is constrained to real space.  If the cursor is past the end of a
line, or in virtual space past a tab, the cursor is moved left to the nearest
"real" column, while the "virtual" column position is saved.  If you move down
again, rs_down() will restore the previous column position if it is not in real
space.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.13.41. rs_page_down() ΓòÉΓòÉΓòÉ

rs_page_down()   PEL

Purpose:  To provide a more convenient page_down() for real space only
movement.

____________

Syntax:   rs_page_down()

____________

Arguments:  none

Description: This function provides a more convenient way of paging down when
the cursor is constrained to real space.  If the cursor is past the end of a
line, or in virtual space past a tab, the cursor is moved left to the nearest
"real" column, while the "virtual" column position is saved.  If you page down
again, rs_page_down() will restore the previous column position if it is not in
real space.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.13.42. rs_page_up() ΓòÉΓòÉΓòÉ

rs_page_up()   PEL

Purpose:  To provide a more convenient page_up() for real space only movement.

____________

Syntax:   rs_page_up()

____________

Arguments:  none

Description: This function provides a more convenient way of paging up when the
cursor is constrained to real space.  If the cursor is past the end of a line,
or in virtual space past a tab, the cursor is moved left to the nearest "real"
column, while the "virtual" column position is saved.  If you page up again,
rs_page_up() will restore the previous column position if it is not in real
space.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.13.43. rs_up() ΓòÉΓòÉΓòÉ

rs_up()   PEL

Purpose:  To provide a more convenient up() for real space only movement.

____________

Syntax:   rs_up()

____________

Arguments:  none

Description: This function provides a more convenient way of moving up when the
cursor is constrained to real space.  If the cursor is past the end of a line,
or in virtual space past a tab, the cursor is moved left to the nearest "real"
column, while the "virtual" column position is saved.  If you move up again,
rs_up() will restore the previous column position if it is not in real space.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.13.44. scroll_down_1() ΓòÉΓòÉΓòÉ

scroll_down_1()   PEL

Purpose: Scroll one line toward the end of the buffer.

____________

Syntax: void scroll_down_1()

____________

Description: The scroll_down_1() function scrolls the text in the current
window toward the end of the buffer by one line.  This has the effect of making
the text in the window appear to move up.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.45. scroll_down_half() ΓòÉΓòÉΓòÉ

scroll_down_half()   PEL

Purpose: Scrolls toward end of buffer by half a window.

____________

Syntax: void scroll_down_half()

____________

Description: The scroll_down_half() function scrolls the text in the current
window toward the end of the buffer by a number of lines equivalent to half the
window height.  This has the effect of making the text in the window appear to
move up.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.46. scroll_horizontal() ΓòÉΓòÉΓòÉ

scroll_horizontal()   Primitive

Purpose: Move text right or left while cursor maintains position.

____________

Syntax: int scroll_horizontal([int offset [, int pan]]) pan]])

____________

Description: The scroll_horizontal() function scrolls the text in the current
window by the number of columns indicated by the offset argument.  Positive
values for offset allow viewing text off-window to the right while negative
values make text toward the beginning of the line visible.  If the offset
argument is omitted the text is scrolled one column right.

The cursor may either scroll or pan as a result of the scroll_horizontal()
function.  When panning, the cursor attempts to maintain its position relative
the window regardless of the motion of text.  When scrolling, it attempts to
maintain its position within the buffer.

You may determine whether this function causes the cursor to scroll or pan by
supplying the pan argument.  When pan is zero the cursor will scroll. Other
values for pan will cause the cursor to pan. If you do not supply the pan
argument, cursor action is determined by the condition of the scroll_means_pan
variable.

The maximum number of columns text may be scrolled to the right is equal to the
number of visible columns in the current line.  The maximum number of columns
text may be scrolled to the left is equal to the number of off-window columns
to the left of the window.

____________

Value returned: scroll_horizontal() returns the number of columns scrolled
(negative or positive).  This is normally the same value as the offset
argument, unless offset was greater than allowable limits.  In that case, the
maximum number of columns to scroll is returned.

____________

See also:   scroll_means_pan, scroll_vertical(), buffer_flags


ΓòÉΓòÉΓòÉ 14.13.47. scroll_left_1() ΓòÉΓòÉΓòÉ

scroll_left_1()   PEL

Purpose: Scroll toward start of line by one column.

____________

Syntax:  void scroll_left_1()

____________

Description: The scroll_left_1() function scrolls the text in the current
window toward the beginning of the line by one column.  This has the effect of
making the text in the window appear to move to the right.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.48. scroll_or_pan() ΓòÉΓòÉΓòÉ

scroll_or_pan()   PEL

Purpose: Tells condition of Scroll Lock key.

____________

Syntax: int scroll_or_pan()

____________

Description: The scroll_or_pan() function reports the condition of the Scroll
Lock key.  This value may be used for assignment to the scroll_means_pan
variable.

____________

Value returned: The value returned by the scroll_or_pan() function is zero
(FALSE) if the Scroll Lock key is toggled off.  If the Scroll Lock key is
toggled on the function returns TRUE (1). scroll_right_1()

Purpose: Scroll toward end of line by one column.

____________

Syntax:  int scroll_right_1

____________

Description: The scroll_right_1() function scrolls the text in the current
window toward the end of current line by one column.  This has the effect of
making the text in the window appear to move to the left.

____________

Value returned: No useful value is returned by this function. scroll_up_1()

Purpose: Scrolls toward start of buffer by one line.

____________

Syntax:  void scroll_up_1()

____________

Description: The scroll_up_1() function scrolls the text in the current window
toward the beginning of the buffer by one line.  This has the effect of making
the text in the window appear to move down.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.49. scroll_up_half() ΓòÉΓòÉΓòÉ

scroll_up_half()   PEL

Purpose: Scrolls toward start of buffer by half a window.

____________

Syntax: void scroll_up_half()

____________

Description: The scroll_up_half() function scrolls the text in the current
window toward the beginning of the buffer by a number of lines equivalent to
half the window height.  This has the effect of making the text in the window
appear to move down.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.50. scroll_vertical() ΓòÉΓòÉΓòÉ

scroll_vertical()   Primitive

Purpose: Move text up or down while cursor maintains position.

____________

Syntax: int scroll_vertical([int offset [, int pan]])

____________

Description: The scroll_vertical() function scrolls the text in the current
window by the number of lines indicated in the offset argument.  Positive
values for offset scroll text down while negative values scroll toward the
beginning of the buffer.  If the offset argument is omitted the text is
scrolled one line down.

If there are less than offset lines between the cursor position and the
applicable buffer limit, the cursor is moved to the first or last line of the
buffer.

The cursor may either scroll or pan as a result of the scroll_vertical()
function.  When panning, the cursor attempts to maintain its position relative
the window regardless of the motion of text.  When scrolling, it attempts to
maintain its position within the buffer.

You may dictate whether this function causes the cursor to scroll or pan by
supplying the pan argument.  When pan is zero the cursor will scroll. Other
values for pan will cause the cursor to pan. If you do not supply the pan
argument, cursor action is determined by the condition of the scroll_means_pan
variable.

____________

Value returned: scroll_vertical() returns the number of lines scrolled
(negative or positive).  This is normally the same value as the offset
argument, unless offset was greater than allowable limits.  In that case, the
maximum number of lines to scroll is returned.


ΓòÉΓòÉΓòÉ 14.13.51. scroll_window_bottom() ΓòÉΓòÉΓòÉ

scroll_window_bottom()   PEL

Purpose: Scroll cursor line to position relative to window bottom

____________

Syntax: void scroll_window_bottom([int offset])

____________

Description: The scroll_window_bottom() function scrolls the line containing
the cursor to a position offset lines from the bottom of the window.  If the
offset argument is omitted or is a value less than 0, the cursor line becomes
the bottom line in the window.

The operation of this function is affected by the state of the scroll_means_pan
variable and the scroll lock key.  Refer to the description of the variable
scroll_means_pan for an explanation.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.52. scroll_window_middle() ΓòÉΓòÉΓòÉ

scroll_window_middle()   PEL

Purpose: Scroll cursor line to position relative to window center.

____________

Syntax: void scroll_window_middle([int offset])

____________

Description: The scroll_window_middle() function scrolls the line containing
the cursor to a position offset lines from the center of the window.  Positive
values for offset place the line below the center of the window, while negative
values place it above the center.  If the offset argument is omitted or is 0,
the cursor line becomes the center line of the window.

The operation of this function is affected by the state of the scroll_means_pan
variable and the scroll lock key.  Refer to the description of the variable
scroll_means_pan for an explanation.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.53. scroll_window_top() ΓòÉΓòÉΓòÉ

scroll_window_top()   PEL

Purpose: Scroll cursor line to position relative window top

____________

Syntax: void scroll_window_top([int offset])

____________

Description: The scroll_window_top() function scrolls the line containing the
cursor to a position offset lines from the top of the window.  If the offset
argument is omitted or is a value less than 0, the cursor line becomes the top
line in the window.

The operation of this function is affected by the state of the scroll_means_pan
variable and the scroll lock key.  Refer to the description of the variable
scroll_means_pan for an explanation.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.54. skip_whitespace() ΓòÉΓòÉΓòÉ

skip_whitespace()   PEL

Purpose: Move cursor to beginning of text on current line.

____________

Syntax: void skip_whitespace()

____________

Description: The skip_whitespace() function moves the cursor to the first
character on the current line that is not a whitespace character (space or
tab).  The function is not affected by the position of the cursor within the
line prior to invoking skip_whitespace().  If the line contains only whitespace
the cursor moves to the end of the line.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.13.55. up() ΓòÉΓòÉΓòÉ

up()   Primitive

Purpose: Move the cursor by lines toward the top of the buffer.

____________

Syntax: int up([int lines])

____________

Description: The up() function moves the cursor the number of lines found in
the lines argument toward the beginning of the buffer.  If the lines argument
is not supplied, one line is assumed.

Negative values for lines are allowed and result in the cursor moving in the
opposite direction.  In other words, calling up() with -3 as the argument is
the as calling down() with 3 as the argument.

The column position of the cursor resulting from a call to up() may be affected
by the buffer_flags variable described above.  If movement into VIRTUAL SPACE
is allowed, the cursor always maintains the same column position at its new
line location.

If movements into VIRTUAL SPACE are disallowed, the column position may change.
When the up() function would position the cursor beyond the end-of-line, it
moves to the nearest column on the new line location which contains a
character.  If up() moves the cursor into a tab, the cursor always moves to the
beginning of the tab.

If there are fewer lines remaining between the cursor position and the
beginning of the buffer than the lines argument specifies, the cursor is moved
to the first line of the buffer.  A short beep is then issued from the speaker.

____________

Value returned: The up() function returns the actual number of lines traversed.
This will be the same number as the lines argument, except when there are too
few lines between the cursor position and the beginning of the buffer to
execute the move completely.


ΓòÉΓòÉΓòÉ 14.13.56. up_whitespace() ΓòÉΓòÉΓòÉ

up_whitespace()   PEL

Purpose:  Move cursor up to the begining of whitespace.

____________

Syntax:   void up_whitespace()

____________

Arguments: none.

Description: The up_whitespace() function moves the cursor up in the buffer,
remaining in the same column, until it reaches the begining of whitespace for
that column.  If BUFFER_REAL_SPACE_ONLY is on, this function may not have the
desired effect.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.13.57. wp ΓòÉΓòÉΓòÉ

wp()   PEL

Purpose:  Sets word processing mode options.

____________

Syntax:   int wp(int on_off, int wrap_continous, int carry_comments)

____________

Arguments:

o onoff - if 1, word processing is enabled and word wrap occurs otherwise
  disables word processing mode.
o wrap_continous - if 1, wraps paragraph when you add new text to a line of an
  existing paragraph. Otherwise new text will not wrap unless you execute
  wrap_paragraph().  Word processing must be enabled for the wrap_continous
  argument to work.
o carry_comment - if 1 and your left margin is set to a value greater than
  zero, the characters in the columns preceding the left margin are copied to
  the beginning of the new line when you press [Enter].  This feature is
  especially useful when you write comment blocks.

Description: The wp() functions enables or disables word processing mode in the
editor.  The arguments supplied to the function determine the word processing
mode settings.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.14. Notebook ΓòÉΓòÉΓòÉ

append_notebook_page()
          Appends a page to a notebook
begin_notebook()
          Displays and enables a notebook dialog box
count_notebook_pages()
          Counts the number pages in a notebook
create_notebook_template()
          Creates a blank notebook template
create_page()
          Creates a new page in a notebook.
create_page_template()
          Creates a blank notebook page template
delete_notebook()
          Deletes a notebook and frees all associated memory
delete_notebook_page()
          Removes a page from a notebook
delete_page()
          Delete a page from a notebook.
get_notebook_page_dialog()
          Retrieves the dialog window associated with a notebook page
insert_notebook_page_after()
          Inserts a notebook page after another page
insert_notebook_page_at_top()
          Inserts a page as the first page of the notebook
insert_notebook_page_before()
          Inserts a notebook page before another page
set_notebook_backpages()
          Sets where the notebook pages intersect
set_notebook_binder_type()
          Sets the binder type for a notebook
set_notebook_button_size()
          Sets the size of the notebook arrow buttons in pixels
set_notebook_major_tab_size()
          Sets the size of the major tabs in pixels
set_notebook_minor_tab_size()
          Sets the size of the major tabs in pixels
set_notebook_page_dialog()
          Changes the dialog window associated with a notebook page
set_notebook_page_stat_text()

set_notebook_page_tab_text()
          Sets the text displayed on the tab for a notebook page
set_notebook_status_align()
          Sets the text alignment of the status area in a notebook.
set_notebook_tab_align()
          Sets the alignment of notebook tab text
set_notebook_tab_location()
          Sets location of the major tabs
set_notebook_tab_type()
          Sets the style of notebook tabs
settings_notebook()
          Display the settings notebook
turnto_notebook_page()
          Brings a notebook page to the top of the notebook


ΓòÉΓòÉΓòÉ 14.14.1. append_notebook_page() ΓòÉΓòÉΓòÉ

append_notebook_page()   Primitive

Purpose: Appends a page to a notebook

____________

Syntax: long append_notebook_page(long nbid,long pageid[, string stat_text[,
string tab_text [, short tab_type, [ short auto_size ]]]])

____________

Description: The append_notebook_page() function appends a page to a notebook
dialog box. The nbid argument contains the notebook id.  The nbid argument must
be a valid notebook id returned from the create_notebook functions. The pageid
argument contains the page id to append into the notebook. This argument must
be a valid page id return from the create_page functions. The optional
stat_text argument contains the text to display on the notebook page status
area. The optional tab_text argument contains the text to display on the
notebook tab associated with the notebook page. The optional tab_type argument
contains style of the tab to use for the notebook page. The auto_size argument
allows the notebook to automatically resize itself if the notebook page is
larger than the notebook.  The default is TRUE.

____________

Value returned: This function returns the page id of the notebook page in the
notebook.


ΓòÉΓòÉΓòÉ 14.14.2. begin_notebook() ΓòÉΓòÉΓòÉ

begin_notebook()   Primitive

Purpose: Displays and enables a notebook dialog box

____________

Syntax: void begin_notebook(long nbid)

____________

Description: The begin_notebook() function displays a notebook dialog box. The
nbid argument contains the id of the notebook dialog box to display.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.3. count_notebook_pages() ΓòÉΓòÉΓòÉ

count_notebook_pages()   Primitive

Purpose: Counts the number pages in a notebook

____________

Syntax: short count_notebook_pages(long nbid)

____________

Description: The count_notebook_pages() function counts the number of notebook
pages associated with a notebook. The nbid argument contains the notebook id.

____________

Value returned: The count_notebook_pages() returns the number of notebook pages
associated with the specified notebook.


ΓòÉΓòÉΓòÉ 14.14.4. create_notebook_template() ΓòÉΓòÉΓòÉ

create_notebook_template()   Primitive

Purpose: Creates a blank notebook template

____________

Syntax: long create_notebook_template([[[[[[[macroid callback_id], long
parent], string label], short x0], short y0], short width], short height])

____________

Description: The create_notebook_template() function creates a blank notebook
dialog box.  Notebook pages are added to the notebook template with the
append/insert notebook page functions.

The optional callback_id argument contains the function id to call when a
significant event occurs to the notebook dialog box.  If callback_id is not
specified or is zero then no callback function is used.

The optional parent argument contains the id of the notebook's parent.  If not
specified or zero the editor window is used as the parent.

The optional label argument contains the caption or title bar text of the
notebook.

The optional x0 argument contains the initial x coordinate of the notebook
dialog box.

The optional y0 argument contains the initial y coordinate of the notebook
dialog box.

The optional width argument contains the initial width of the notebook dialog
box.

The optional height argument contains the initial height of the notebook dialog
box.

____________

Value returned: The create_notebook_template() returns the id of the newly
created notebook dialog box on success. If create_notebook_template() fails
FALSE is returned.


ΓòÉΓòÉΓòÉ 14.14.5. create_page() ΓòÉΓòÉΓòÉ

create_page()   Primitive

Purpose:  Creates a new page in a notebook.

____________

Syntax:   long create_page(funcid callback_id, long par, long resid, [str
szFile])

____________

Arguments:

o callback_id - function id of the callback
o par -
o resid -
o szFile -

Description: The create_page() function creates a page that can be inserted
into a notebook.

____________

Value returned: Dialog handle of the newly created page.


ΓòÉΓòÉΓòÉ 14.14.6. create_page_template() ΓòÉΓòÉΓòÉ

create_page_template()   Primitive

Purpose: Creates a blank notebook page template

____________

Syntax: long create_page_template(macroid callback_id,long parent,[[[[short x0,
short y0], short width], short height])

____________

Description: The create_page_template() function creates a blank notebook page
template.  Controls are added to the notebook page template the same way
controls are added to a dialog box.  The notebook page template is added to a
notebook with one of the insert/append notebook page functions. The callback_id
argument contains the function id to call when a significant event occurs with
the notebook page. The parent argument contains the parent window of the
notebook page template.  If the parent argument is zero then the editor window
is used as the parent otherwise parent must be a valid dialog box id returned
from one of the create_notebook functions. The optional x0 argument contains
the initial x coordinate of the notebook page in pixels. The optional y0
argument contains the initial y coordinate of the notebook page in pixels. The
optional width argument contains the initial width of the notebook page in
pixels. The optional height argument contains the initial height of the
notebook page in pixels.

____________

Value returned: The create_page_template() function returns the id of the newly
created notebook page template.  The return value is used when adding controls
to the notebook and added the page template to a notebook.


ΓòÉΓòÉΓòÉ 14.14.7. delete_page() ΓòÉΓòÉΓòÉ

delete_page   Primitive

Purpose:  Delete a page from a notebook.

____________

Syntax:   delete_page(long dlghand)

____________

Arguments:

o dlghand - handle of the page to be deleted.

Description: The delete_page() function deletes the specified page from a
notebook.  The processing is similar to the delete_dialog() function.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.14.8. delete_notebook() ΓòÉΓòÉΓòÉ

delete_notebook()   Primitive

Purpose: Deletes a notebook and frees all associated memory

____________

Syntax: void delete_notebook(long nbid)

____________

Description: The delete_notebook() function deletes the specified notebook and
frees all associated memory. The notebook id becomes invalid after this call
and can no longer be used in any notebook functions. The nbid argument contains
the id of the notebook dialog box to delete.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.9. delete_notebook_page() ΓòÉΓòÉΓòÉ

delete_notebook_page()   Primitive

Purpose: Removes a page from a notebook

____________

Syntax: void delete_notebook_page(long nbid, long pageid)

____________

Description: The delete_notebook_page() function removes a page from a
notebook.  The page is no longer visible on the notebook. The nbid argument
contains the notebook id.  The nbid argument must be a valid notebook id
returned from the create_notebook functions. The pageid argument contains the
page of the notebook to delete. The pageid argument must be a valid page
returned from one of the insert/append notebook functions.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.10. get_notebook_page_dialog() ΓòÉΓòÉΓòÉ

get_notebook_page_dialog()      Primitive

Purpose: Retrieves the dialog window associated with a notebook page

____________

Syntax: long get_notebook_page_dialog(long nbid, long pageid)

____________

Description: The get_notebook_page_dialog() function retrieves the dialog
window associated with a notebook page. The nbid argument contains the notebook
id.  The nbid argument must be a valid notebook id returned from the
create_notebook functions. The pageid argument contains the page of the
notebook to associate to the dialog window.  The pageid argument must be a
valid page returned from one of the insert/append notebook functions.

____________

Value returned: This function returns the dialog id associated with the
notebook page if successfull, otherwise 0 is returned.


ΓòÉΓòÉΓòÉ 14.14.11. insert_notebook_page_after() ΓòÉΓòÉΓòÉ

insert_notebook_page_after()   Primitive

Purpose: Inserts a notebook page after another page

____________

Syntax: long insert_notebook_page_after(long nbid, long after_page, long pageid
[, string stat_text [, string tab_text [, short tab_type, [ short auto_resize
]]]])

____________

Description: The insert_notebook_page_before() function inserts a page after
another page of the notebook. The nbid argument contains the notebook id.  The
nbid argument must be a valid notebook id returned from the create_notebook
functions. The after_page argument contains the page of the notebook to insert
after.  The after_page argument must be a valid page returned from one of the
insert/append notebook functions. The pageid argument contains the page id to
insert into the notebook. This argument must be a valid page id return from the
create_page functions. The optional stat_text argument contains the text to
display on the notebook page status area. The optional tab_text argument
contains the text to display on the notebook tab associated with the notebook
page. The optional tab_type argument contains style of the tab to use for the
notebook page. The auto_size argument allows the notebook to automatically
resize itself if the notebook page is larger than the notebook.  The default is
TRUE.

____________

Value returned: This function returns the page id of the notebook page in the
notebook.


ΓòÉΓòÉΓòÉ 14.14.12. insert_notebook_page_at_top() ΓòÉΓòÉΓòÉ

insert_notebook_page_at_top()   Primitive

Purpose: Inserts a page as the first page of the notebook

____________

Syntax: long insert_notebook_page_at_top(long nbid,long pageid [, string
stat_text [, string tab_text [, short tab_type [,short auto_size]]]])

____________

Description: The insert_notebook_page_at_top() function inserts a page as the
first page of the notebook. The nbid argument contains the notebook id.  The
nbid argument must be a valid notebook id returned from the create_notebook
functions. The pageid argument contains the page id to append into the
notebook. This argument must be a valid page id return from the create_page
functions. The optional stat_text argument contains the text to display on the
notebook page status area. The optional tab_text argument contains the text to
display on the notebook tab associated with the notebook page. The optional
tab_type argument contains style of the tab to use for the notebook page. The
auto_size argument allows the notebook to automatically resize itself if the
notebook page is larger than the notebook.  The default is TRUE.

____________

Value returned: This function returns the page id of the notebook page in the
notebook.


ΓòÉΓòÉΓòÉ 14.14.13. insert_notebook_page_before() ΓòÉΓòÉΓòÉ

insert_notebook_page_before()   Primitive

Purpose: Inserts a notebook page before another page

____________

Syntax: long insert_notebook_page_before(long nbid, long before_page, long
pageid [, string stat_text [, string tab_text [, short tab_type, [ short
auto_resize ]]]])

____________

Description: The insert_notebook_page_before() function inserts a page before
another page of the notebook. The nbid argument contains the notebook id.  The
nbid argument must be a valid notebook id returned from the create_notebook
functions. The before_page argument contains the page of the notebook to insert
before.  The before_page argument must be a valid page returned from one of the
insert/append notebook functions. The pageid argument contains the page id to
insert into the notebook. This argument must be a valid page id return from the
create_page functions. The optional stat_text argument contains the text to
display on the notebook page status area. The optional tab_text argument
contains the text to display on the notebook tab associated with the notebook
page. The optional tab_type argument contains style of the tab to use for the
notebook page. The auto_size argument allows the notebook to automatically
resize itself if the notebook page is larger than the notebook.  The default is
TRUE.

____________

Value returned: This function returns the page id of the notebook page in the
notebook.


ΓòÉΓòÉΓòÉ 14.14.14. set_notebook_backpages() ΓòÉΓòÉΓòÉ

set_notebook_backpages()   Primitive

Purpose: Sets where the notebook pages intersect

____________

Syntax: void set_notebook_backpages(long nbid, short style)

____________

Description: The set_notebook_backpages() function sets the intersection point
for all the notebook pages.  There are 4 possible intersection points of the
notebook pages; bottom right, bottom left, top right, and top left. The nbid
argument contains the notebook id. The style argument contains the desired
intersection points for the notebook pages.  The valid values for style are:

o 0 - bottom right
o 1 - bottom left
o 2 - top right
o 3 - top left

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.15. set_notebook_binder_type() ΓòÉΓòÉΓòÉ

set_notebook_binder_type()   Primitive

Purpose: Sets the binder type for a notebook

____________

Syntax: void set_notebook_binder_type(long nbid, short type)

____________

Description: The set_notebook_binder_type() function sets the type of binder
displayed on the notebook page.  The available binder types are solid and
spiral. The nbid argument contains the id of the notebook dialog box. The type
argument contains the type of binder to use.  The type arugument must contain
one of the following values:

o 0 - solid binder
o 1 - spiral binder

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.16. set_notebook_button_size() ΓòÉΓòÉΓòÉ

set_notebook_button_size()   Primitive

Purpose: Sets the size of the notebook arrow buttons in pixels

____________

Syntax: void set_notebook_button_size(long nbid, short width, short height)

____________

Description: The set_notebook_button_size() function sets the size of the arrow
buttons on a notebook dialog box. The arrow buttons are usually located in the
lower right corner of the notebook page. The nbid argument contains the id of
the notebook dialog box. The width argument contains the new pixel width of the
arrow buttons. The height argument contains the new pixel height of the arrow
buttons.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.17. set_notebook_major_tab_size() ΓòÉΓòÉΓòÉ

set_notebook_major_tab_size()   Primitive

Purpose: Sets the size of the major tabs in pixels

____________

Syntax: void set_notebook_major_tab_size( long nbid, short width, short height)

____________

Description: The set_notebook_major_tab_size() function sets the size of major
tabs.  This function affects all major tabs for the notebook dialog box.  Major
tabs are usually aligned vertically along the right hand side of the dialog
box.  Major tabs can have minor tabs associated with them. The nbid argument
contains the id of the notebook dialog box. The width argument contains the new
pixel width of the major tabs. The height argument contains the new pixel
height of the major tabs.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.18. set_notebook_minor_tab_size() ΓòÉΓòÉΓòÉ

set_notebook_minor_tab_size()   Primitive

Purpose: Sets the size of the major tabs in pixels

____________

Syntax: void set_notebook_minor_tab_size(long nbid, short width, short height)

____________

Description: The set_notebook_minor_tab_size() function sets the size of minor
tabs.  This function affects all minor tabs for the notebook dialog box.  Minor
tabs are always associated with a major tab and are usually aligned
horizontally along the bottom of the dialog box.  Minor tabs are only visible
when the assocaited major tab is selected. The nbid argument contains the id of
the notebook dialog box. The width argument contains the new pixel width of the
minor tabs. The height argument contains the new pixel height of the minor
tabs.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.19. set_notebook_page_dialog() ΓòÉΓòÉΓòÉ

set_notebook_page_dialog()   Primitive

Purpose: Changes the dialog window associated with a notebook page

____________

Syntax: long set_notebook_page_dialog(long nbid, long pageid, long dlgid)

____________

Description: The set_notebook_page_dialog() function changes the dialog window
associated with a notebook page. The nbid argument contains the notebook id.
The nbid argument must be a valid notebook id returned from the create_notebook
functions. The pageid argument contains the page of the notebook to associate
to the dialog window.  The pageid argument must be a valid page returned from
one of the insert/append notebook functions. The dlgid argument contains the
new dialog box to associate with the notebook page.  The dlgid argument must be
a valid id returned from one of the create_dialog or create_page functions.

____________

Value returned: Returns TRUE if page was successfully changed, FALSE otherwise.


ΓòÉΓòÉΓòÉ 14.14.20. set_notebook_page_stat_text() ΓòÉΓòÉΓòÉ

set_notebook_page_stat_text()   Primitive

Purpose:

____________

Syntax: void use_resource_file(opt string)

____________

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.14.21. set_notebook_page_tab_text() ΓòÉΓòÉΓòÉ

set_notebook_page_tab_text()   Primitive

Purpose: Sets the text displayed on the tab for a notebook page

____________

Syntax: void set_notebook_page_tab_text(long nbid, long pageid, string
tab_text)

____________

Description: The set_notebook_page_tab_text() function sets the text displayed
on the tabe for a notebook page. The nbid argument contains the notebook id.
The nbid argument must be a valid notebook id returned from the create_notebook
functions. The pageid argument contains the page of the notebook to whose tab
text will be changed.  The pageid argument must be a valid page returned from
one of the insert/append notebook functions.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.14.22. set_notebook_status_align() ΓòÉΓòÉΓòÉ

set_notebook_status_align()   Primitive

Purpose: Sets the text alignment of the status area in a notebook.

____________

Syntax: void set_notebook_status_align( long nbid, short alignment)

____________

Description: The set_notebook_status_align() function sets the alignment of the
status area text at the bottom of the notebook page.  Valid alignment settings
are left, right, and center. The nbid argument contains the notebook id. The
alignment argument contains the new alignment for the status area text.  Valid
values for alignment are:

o 0 - left
o 1 - center
o 2 - right

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.23. set_notebook_tab_align() ΓòÉΓòÉΓòÉ

set_notebook_tab_align()   Primitive

Purpose: Sets the alignment of notebook tab text

____________

Syntax: void set_notebook_tab_align(long nbid, short alignment)

____________

Description: The set_notebook_tab_align() function sets the alignment of the
text displayed in a notebook tab.  The possible alignments are left, center,
and right. The nbid argument contains the notebook id. The alignment argument
contains the desired alignment for the notebook tab text.  The valid values for
alignment are:

o 0 - left
o 1 - center
o 2 - right

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.24. set_notebook_tab_location() ΓòÉΓòÉΓòÉ

set_notebook_tab_location()   Primitive

Purpose: Sets location of the major tabs

____________

Syntax: void set_notebook_tab_location(long nbid, short loc)

____________

Description: The set_notebook_tab_location() function sets the location of the
major tabs.  Minor tabs are adjusted appropriately when the major tab location
is changed. Major tabs can be positioned on the left, right, top, or bottom
sides of the notebook. The nbid argument contains the id of the notebook dialog
box. The type argument contains the type of binder to use.  The type argument
must contain one of the following values:

o 0 - left
o 1 - right
o 2 - top
o 3 - bottom

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.25. set_notebook_tab_type() ΓòÉΓòÉΓòÉ

set_notebook_tab_type()   Primitive

Purpose: Sets the style of notebook tabs

____________

Syntax: void set_notebook_tab_type(long nbid, short type)

____________

Description: The set_notebook_tab_type() function sets the style of the tabs
contained on the notebook.  The possible styles of tabs are square, rounded, or
polygon. The nbid argument contains the id of the notebook dialog box. The type
argument contains the style of the tabs.  The type arugument must contain one
of the following values:

o 0 - square tabs
o 1 - rounded tabs
o 2 - polygon tabs

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.14.26. settings_notebook() ΓòÉΓòÉΓòÉ

settings_notebook()   PEL

Purpose:  Display the settings notebook

____________

Syntax:   void settings_notebook()

____________

Arguments: none.

Description: The settings_notebook() function displays the settings notebook.
Many of the editor can be viewed and set in the settings notebook.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.14.27. turnto_notebook_page() ΓòÉΓòÉΓòÉ

turnto_notebook_page()   Primitive

Purpose: Brings a notebook page to the top of the notebook

____________

Syntax: void turnto_notebook_page(long nbid, long pagid)

____________

Description: The turnto_notebook_page() function brings a notebook page to the
top of the notebook. The nbid argument contains the notebook id.  The nbid
argument must be a valid notebook id returned from the create_notebook
functions. The pageid argument contains the page of the notebook to delete. The
pageid argument must be a valid page returned from one of the insert/append
notebook functions.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.15. PEL Programming ΓòÉΓòÉΓòÉ

The Programming and PEL category contains primarily the variables and functions
inherited from PEL.  This category is augmented by several functions that
assist in the programming and debugging of extension language programs.  Many
of these functions and variables serve several purposes and therefore are also
listed in other categories.

Among the functions and variables unique to this category are the AWK print()
function and the OFS and ORS variables provided for its sole use.  The print()
function outputs a list of arguments to the standard output device. The OFS
string or Output Field Separator is sent to the output device between each pair
of arguments given to the print() function.  Each call to print() ends with the
ORS string or Output Record Separator being sent to the device.

Another variable unique to this category is the SUBSEP variable.  PEL uses it
when simulating multidimensional arrays using the single dimension arrays
provided.  You access the elements of these additional dimensions by using the
split() function, supplying the SUBSEP variable as an argument.

The function_caller(), function_id() and function_name() routines provide some
assistance in tracing the progress of your functions.  However, they are also
useful in controlling program flow and translating between the two methods of
functions:  by numeric id and by name string.

Another function useful in determining program flow is argcount().  It may be
desirable for your function to take different actions depending on how many
arguments have been passed to it.  The argcount() function gives you a method
of determining how many arguments have been passed from any given function
call. The number of arguments passed may often be determined by other means.
Arguments that have been omitted will receive a value of 0 or will be an empty
string. If, however, 0 or an empty string is an acceptable value for the
argument, then argcount() provides the only method of determining the number of
arguments passed.

Although you will find descriptions of the sub() and gsub() functions in the
"String Manipulation" chapter, it is worth mentioning again that these are the
only functions in AWK that  modify any of their arguments.  Since there are no
pointers in AWK, all arguments to functions are passed by value rather than by
passing a pointer to the actual variable.  This means that a function cannot
modify the original variable because it doesn't know where the variable is.  It
only has the value contained in the variable.  Nonetheless, the sub() and
gsub() functions do modify the string argument they receive.  Reportedly this
is done by magic, however, you are free to suspect cheating.

argcount()
          Reports the number of arguments passed to the current function.
ctags_make()
          Creates a C language tags file from C source code.
display_array()
          To display the contents of an array in a selection dialog.
execute_auto()
          To call a function with the word at the current cursor location as a
          parameter.
expand_template()
          Expand a template if one can be located at or near the cursor.
expand_template_key()
          Expand symbol near cursor if possible
function_caller()
          Reports the name of the calling function.
function_id()
          Reports the id associated with a function name.
function_name()
          Reports the name associated with a function id.
goto_matching()
          To move the cursor to the symbol matching the symbol at the current
          cursor location.
mark_matching()
          To highlight the region between the symbol at the cursor and its
          matching pair.
mark_matching_next()
          To highlight the region between the next two matching symbols.
next_field_key()
          Moves the cursor to the next field of the template.
nop()
          Provides a method of assigning no task to a table entry.
optional_function()
          To call a specified function with parameters if that function exists,
          otherwise fail without raising an error.
pe()
          Toggles pausing between messages.
peltags()
          To locate the pel source code for a specified symbol.
peltags_auto()
          To locate the pel source code for the symbol at the current cursor
          position.
peltags_make()
          To create a .tag file for the pel source code.
remove_expand_template_key()
          To remove a key currently assigned to perform template expansion.
remove_next_field_key()
          To remove a key currently assigned to perform template field
          advancement.
set_environment()
          Set an environment variable to the specified value.
set_expand_template_key()
          To assign the key for which template expansion occurs.
set_next_field_key()
          To assign the key which advances to the next field of a template.
split()
          Create an array from a string.
tags()
          To search through the tags files in tags_path for a symbol
tags_auto()
          To search through the tags files in tags_path for the word at the
          current cursor position.
toggle_electric()
          Toggles template expansion on or off.
typeof()
          Reports the data type of a variable in string form.


ΓòÉΓòÉΓòÉ 14.15.1. argcount() ΓòÉΓòÉΓòÉ

argcount()   Primitive

Purpose:  Reports the number of arguments passed to the current function.

____________

Syntax:  int argcount()

____________

Description: The argcount() function tells how many arguments were actually
passed to the function currently executing.  This function enhances the ability
to write PEL functions that can accept a variable number of arguments.

If arguments are omitted when calling a function the values the function
receives for these arguments will be 0 or an empty string.  In some cases it is
useful to distinguish an omitted argument from one that was supplied as one of
these values. The argcount function provides a method of doing this.

____________

Value returned:

The value returned by the argcount() function is the number of arguments
supplied in the function call to the current function.


ΓòÉΓòÉΓòÉ 14.15.2. ctags_make() ΓòÉΓòÉΓòÉ

ctags_make()   PEL

Purpose:  Creates a C language tags file from C source code.

____________

Syntax:   void ctags_make(str listOfFiles, str extraString)

____________

Arguments:

listOfFile - space separated list of files.

extraString - string which validates a function definition.

Description: The ability to quickly view function definitions and constant
#defines in C and C++ is invaluable for any software developer.  This function
will parse C and C++ source code files for function names, #defines, typedefs,
structure definitions and class declarations, and then save all of these
symbols and their locations in a file named ctags.tag.  Later, when you wish to
view the source code for any one of these symbols, you simply call the function
tags() with the name of the symbol as a parameter, or call tags_auto() with
your cursor placed on the symbol, and the appropriate file will be loaded with
the source code visible.

When you run ctags_make(), it will report the date that the tags file was last
updated, and will prompt you for the extensions of the files you wish to parse.

The editor's current working directory must be the directory you wish to create
the .tag file for, so you will probably want to call cd() first.

Note:  parsing source files takes a long time, so be prepared to let the editor
run in the background for a while until it is done parsing.  It will beep to
let you know it is done.

____________

____________

Value returned:  None.


ΓòÉΓòÉΓòÉ 14.15.3. display_array() ΓòÉΓòÉΓòÉ

display_array()   PEL

Purpose:  To display the contents of an array in a selection dialog.

____________

Syntax:   display_array( array the_array, [str name] )

____________

Arguments:

o the_array - the array to display
o name    - name to use in the dialog title

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.4. execute_auto() ΓòÉΓòÉΓòÉ

execute_auto()   PEL

Purpose:  To call a function with the word at the current cursor location as a
parameter.

____________

Syntax:   execute_auto( str fun, [regex symbol_regex] )

____________

Arguments:

o fun      - function to call
o symbol_regex - definition of a word, optional

Description: There are many useful pel functions such as search and grep which
take a string as a parameter to perform an operation on. As often-used utility
functions, the user might like to call these functions from an assigned
keystroke, and will often want to perform the function's operation on either
the current selected block or on the word at the current cursor location.
execute_auto() will call the specified function with one parameter: the text
currenty highlighted, or if nothing is highlighted, the word at the current
cursor location.  For example:  assign_key( "<F10>", "execute_auto grep" )
causes the F10 key to, in effect, be assigned to grep() with either the
highlighted block or the current word as a parameter.

____________

Value returned: If successful, execute_auto() returns the value returned by the
function it calls.  If no function was specified, it returns either the text
currently selected or the word at the cursor location.  If no text is selected
and a word cannot be found at the current cursor location, a warning message is
displayed and FALSE is returned.


ΓòÉΓòÉΓòÉ 14.15.5. expand_template() ΓòÉΓòÉΓòÉ

expand_template()   PEL

Purpose:  Expand a template if one can be located at or near the cursor.

____________

Syntax:   int expand_template( int noError )

____________

Arguments:

o noError - flag indicating whether the error mesages should be displayed

Description: The expand_template() function looks at the symbol under the
cursor and tries to expand it.  The template it uses is based on the extension
and can be set on the extensions page of the notebook.  To use this function,
the editor must be in electric_mode.

____________

Value returned:

TRUE - template successfully expanded

FALSE - template not expanded


ΓòÉΓòÉΓòÉ 14.15.6. expand_template_key() ΓòÉΓòÉΓòÉ

expand_template_key()   PEL

Purpose:  Expand symbol near cursor if possible

____________

Syntax:   void expand_template_key()

____________

Arguments: none

Description: expand_template_key() expands the symbol near the cursor if
possible, but if it can not be expanded, the default action of the "key" is
taken.  The "key" is the keystroke combination used to invoke the function.

____________

Value returned: none


ΓòÉΓòÉΓòÉ 14.15.7. function_caller() ΓòÉΓòÉΓòÉ

function_caller()   Primitive

Purpose: Reports the name of the calling function.

____________

Syntax:  str function_caller()

____________

Description: The function_caller() function tells which function, by name,
called the function currently executing.  It is primarily used to select
between courses of action, often depending on whether the function was invoked
from the keyboard or not.

____________

Value returned:

The value returned by function_caller() is a string containing the name of the
invoking function.  If the function was called from the keyboard it returns the
string "Keyboard".  If called by an internal primitive rather than a PEL
function, the string returned is "Primitive".


ΓòÉΓòÉΓòÉ 14.15.8. function_id() ΓòÉΓòÉΓòÉ

function_id()   Primitive

Purpose: Reports the id associated with a function name.

____________

Syntax:  funcid function_id(any function [, any arg2 ... [, any. arg5]])

____________

Description: The function_id() function provides a method of discovering the
numeric id associated with a function.  The function is specified by named in
the function argument.

In addition, this function provides access to an advanced the editor
programming feature called "anonymous functions".  These are transient
functions that provide a programming short-cut.  These functions do not appear
in the source code as functions. They are essentially other existing functions
called with a defined set of constant arguments.

You might write a function to create a certain size window in the following
conventional manner: function my_window {   create_window(5,5,20,70) }  You may
alternately use function_id() to obtain the function id of such a function
without ever writing it:

fid = function_id("create_window 5 5 20 70")

This is the method used internally for several features, including assigning to
keys functions that require arguments. This use of function_id() sometimes
requires supplying additional arguments to function_id().  This is freely
allowed. The above example could also be written:

fid = function_id("create_window",5,5,20,70)

____________

Value returned:

The value returned by the function_id() function is the corresponding function
id if the function has been defined. Otherwise, the function returns a zero
value.


ΓòÉΓòÉΓòÉ 14.15.9. function_name() ΓòÉΓòÉΓòÉ

function_name()   Primitive

Purpose: Reports the name associated with a function id.

____________

Syntax:  str function_name(funcid id)

____________

Description: The function_name() function provides a method of discovering the
name of a function associated with a numeric function id.  The function id is
specified in the id argument.

____________

Value returned:

The value returned by the function_name() function is a string containing the
name of the function if it has been defined. Otherwise, the function returns an
empty string.


ΓòÉΓòÉΓòÉ 14.15.10. goto_matching() ΓòÉΓòÉΓòÉ

goto_matching()   PEL

Purpose:  To move the cursor to the symbol matching the symbol at the current
cursor location.

____________

Syntax:   goto_matching()

____________

Arguments:  none

Description: When trying to locate the source of a syntax error, oftentimes it
can be difficult to detect unbalanced parentheses or braces in the C language,
begin and end in PASCAL, etc.  This function automates the process of finding
these matching pairs.  If you place the cursor on one of the defined matching
pairs, calling this function will move the cursor to the location of its
matching symbol.

See also:  matching_pairs

____________

Value returned:

TRUE  -  success

FALSE -  failure, either not on a valid symbol, or there is an unbalanced pair


ΓòÉΓòÉΓòÉ 14.15.11. mark_matching() ΓòÉΓòÉΓòÉ

mark_matching()   PEL

Purpose:  To highlight the region between the symbol at the cursor and its
matching pair.

____________

Syntax:   mark_matching()

____________

Arguments:  none

Description: When trying to locate the source of a syntax error, oftentimes it
can be difficult to detect unbalanced parentheses or braces in the C language,
begin and end in PASCAL, etc.  This function automates the process of finding
these matching pairs.  If you place the cursor on one of the defined matching
pairs, calling this function will highlight the text between the current symbol
and its matching symbol.

See also:  matching_pairs

____________

Value returned:

TRUE  -  successful

FALSE -  failure, either not on a valid symbol or could not find the matching
pair


ΓòÉΓòÉΓòÉ 14.15.12. mark_matching_next() ΓòÉΓòÉΓòÉ

mark_matching_next()   PEL

Purpose:  To highlight the region between the next two matching symbols.

____________

Syntax:   mark_matching_next()

____________

Arguments:  none

Description: This function will search forward for the next occurance of one of
the defined matching pairs, and then highlight the region between it and its
own matching symbol.

See also:  matching_pairs

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.13. next_field_key() ΓòÉΓòÉΓòÉ

next_field_key()   PEL

Purpose:  Moves the cursor to the next field of the template.

____________

Syntax:   void next_field_key()

____________

Arguments: none.

Description: The next_field_key() function looks forward in the buffer to find
the next field of the expanded template.  If one is not found, the default
action of the key pressed is taken.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.15.14. nop() ΓòÉΓòÉΓòÉ

nop()   Primitive

Purpose: Provides a method of assigning no task to a table entry.

____________

Syntax: void nop()

____________

Description: The nop() function does nothing.  It does this as quickly and
quietly as possible.

This function is primarily used for assignment to keys in a keymap or other
table where a function must be specified but no action is desired.  For
example, when the nop() function has been assigned to a key, nothing happens
when that key is depressed.

____________

Value returned: No value is returned by this function.


ΓòÉΓòÉΓòÉ 14.15.15. optional_function() ΓòÉΓòÉΓòÉ

optional_function()   PEL

Purpose:  To call a specified function with parameters if that function exists,
otherwise fail without raising an error.

____________

Syntax:   optional_function( str fn_name, [any arg1,... [any arg5]] )

____________

Arguments:

o fn_name - name of the function to call
o arg1   - first argument to the function
o arg2   - second argument to the function
o arg3   - third argument to the function
o arg4   - fourth argument to the function
o arg5   - fifth argument to the function

Description: This function is used to add optional "packages" to the editor.
Normally you would get a pel compiler error if one pel file called a function
from another pel file that was not compiled into the .ae file. However, in the
case of the settings notebook, we wanted to give the user to option of
compiling in certain pel files or not.  So, in order to create optional pages
in the notebook, such as the extension page, we used optional_function() to
create that page.  If the function to create the page was in the .ae file, then
fine, the page appears in the notebook. If not, then fine, you chose not to use
those features of the editor.

____________

Value returned: If the fn_name function exists, the value returned is the value
returned by calling that function.  Otherwise, FALSE is returned.


ΓòÉΓòÉΓòÉ 14.15.16. pe() ΓòÉΓòÉΓòÉ

pe()   PEL

Purpose: Toggles pausing between messages.

____________

Syntax: void pe([int on])

____________

Description: pe() is a tersely named function to modify the pause_on_error
variable, suitable for executing through the PEL interpreter ( ).  When the on
argument is omitted, this function toggles pausing between error messages to
its opposite condition. When the argument is supplied, a zero value turns
pausing off, while other values turn pausing on.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.15.17. peltags() ΓòÉΓòÉΓòÉ

peltags()   PEL

Purpose:  To locate the pel source code for a specified symbol.

____________

Syntax:   peltags( str symbol )

____________

Arguments:

o symbol - the symbol to find the source code for

Description: This function operates similarly to ctags(), and will find the
declarations of pel variables and functions.

See also:  peltags_make(), peltags_auto()

____________

Value returned:

TRUE  -  success, found the source code for the symbol

FALSE -  failure, could not find source for the symbol


ΓòÉΓòÉΓòÉ 14.15.18. peltags_auto() ΓòÉΓòÉΓòÉ

peltags_auto()   PEL

Purpose:  To locate the pel source code for the symbol at the current cursor
position.

____________

Syntax:   peltags_auto()

____________

Arguments:  none

Description:

See also:  peltags(), peltags_make()

____________

Value returned:

TRUE  -  success, found the source code for the symbol

FALSE -  failure, could not find source for the symbol


ΓòÉΓòÉΓòÉ 14.15.19. peltags_make() ΓòÉΓòÉΓòÉ

peltags_make()   PEL

Purpose:  To create a .tag file for the pel source code.

____________

Syntax:   peltags_make()

____________

Arguments:  none

Description: This function operates similarly to ctags_make(), and will create
a file called peltags.tag that contains the locations of all pel functions and
variables.  Note:  Parsing all of the pel source takes quite a while. Leave the
function running in the background while you do other work; it will beep to
tell you it is done.  Note2: This function operates on the current working
directory, so be sure to chdir() to the pel source directory before calling
this function.

See also:  peltags(), peltags_auto()

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.20. remove_expand_template_key() ΓòÉΓòÉΓòÉ

remove_expand_template_key()   PEL

Purpose:  To remove a key currently assigned to perform template expansion.

____________

Syntax:   remove_expand_template_key( str key )

____________

Arguments:

o key - the key you no longer wish to perform template expansion

Description: If you are using template expansion but do not like the default
expansion key, you can use this function to restore that key's normal behavior.
For example, if you remove the default expand template key <Space> with this
function, it will revert to operating as a space bar.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.21. remove_next_field_key() ΓòÉΓòÉΓòÉ

remove_next_field_key()   PEL

Purpose:  To remove a key currently assigned to perform template field
advancement.

____________

Syntax:   remove_next_field_key( str key )

____________

Arguments:

o key - the key you no longer wish to perform template field advancement.

Description: If you are using template expansion but do not like the default
next field key, you can use this function to restore that key's normal
behavior.  For example, if you remove the default next field key <Enter> with
this function, it will revert to operating as an ente key.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.22. set_environment() ΓòÉΓòÉΓòÉ

set_environment()   PEL

Purpose:  Set an environment variable to the specified value.

____________

Syntax:   void set_environment(str env_var, any value)

____________

Arguments:

o env_var - environment variable to change
o value - new value of the environment variable

Description: The set_environment() function allows the user to set system
environment variables from within the editor.  The variable passed as the first
parameter will have the value of the second parameter after this is called.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.15.23. set_expand_template_key() ΓòÉΓòÉΓòÉ

set_expand_template_key()   PEL

Purpose:  To assign the key for which template expansion occurs.

____________

Syntax:   set_expand_template_key( str key )

____________

Arguments:

o key - the keyname to assign template expansion to.

Description: When you enable template expansion, a default key is assigned to
perform the expansion.  However, you may wish to choose a different or
additional key for this purpose.  This function will enable template expansion
for the key you specify, and will keep track of the function previously bound
to that key. When you press the key it will expand a template if you have typed
an abbreviation, and otherwise will call the old function.  In other words,
when there is a template to be expanded, it will expand it, and if not then the
key will behave as it did before.  For example, if you assign the tab key to do
template expansion:  set_expand_template_key( "<Tab>" )  The tab key will
expand defined template abreviations, but will function as a tab key otherwise.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.24. set_next_field_key() ΓòÉΓòÉΓòÉ

set_next_field_key()   PEL

Purpose:  To assign the key which advances to the next field of a template.

____________

Syntax:   set_next_field_key( str key )

____________

Arguments:

o key - The key to make "the next field key"

Description: When you enable template expansion, a default key is assigned to
advance to the next field of a template.  However, you may wish to choose a
different or additional key for this purpose. This function will enable field
advancement for the key you specify, and will keep track of the function
previously bound to that key.  When you press the key it will advance to the
next field of the current template, or if there is no current template, it will
call the old function.  In other words, when there is a field to advance to, it
will advance to it, and if not then the key will behave as it did before.  For
example, if you assign the tab key to do field advancement:
set_next_field_key( "<Tab>" )  The tab key will expand defined template
abreviations, but will function as a tab key otherwise.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.15.25. split() ΓòÉΓòÉΓòÉ

split()   Primitive

Purpose: Create an array from a string.

____________

Syntax: int split(str st, array arr [, str fs])

____________

Description: The split() function makes an AWK array by breaking up the st
argument into fields.  Each of these fields then becomes an element of the
array arr. Each element of the array is sequentially subscripted with numeric
strings.

The fs argument specifies a field separator, which character or characters
determines where one field ends and the next begins.  If the argument is
omitted, the value of the FS variable will be used as a separator.  By default,
FS is a space.

EXAMPLE

split("11:53:45",timeArr,":")

In the resulting array,

  timeArr[1] == "11"
  timeArr[2] == "53"
  timeArr[3] == "45"

____________

Value returned: The value returned by split() is the number of elements added
to the array.


ΓòÉΓòÉΓòÉ 14.15.26. tags() ΓòÉΓòÉΓòÉ

tags()   PEL

Purpose:  To search through the tags files in tags_path for a symbol

____________

Syntax:   tags( str symbol )

____________

Arguments:

o symbol - the symbol to search for

Description: This function searches through the files specified in the
tags_path variable for the functions and variable locations stored in the ┬╖tag
files.  If it finds the symbol, it loads the file tagged, and moves the cursor
to the location of the symbol, usually a function or variable definition.

See also:  tags_auto(), ctags_make(), peltags_make(), peltags(), peltags_auto()

____________

Value returned:

TRUE  -  the symbol was found

FALSE -  the symbol was not found


ΓòÉΓòÉΓòÉ 14.15.27. tags_auto() ΓòÉΓòÉΓòÉ

tags_auto()   PEL

Purpose:  To search through the tags files in tags_path for the word at the
current cursor position.

____________

Syntax:   tags_auto()

____________

Arguments:  none

Description: This function searches through the files specified in the
tags_path variable for the functions and variable locations stored in the .tag
files.  If it finds the symbol, it loads the file tagged, and moves the cursor
to the location of the symbol, usually a function or variable definition.

See also:  tags(), ctags_make(), peltags_make(), peltags(), peltags_auto()

____________

Value returned:  the symbol searched for


ΓòÉΓòÉΓòÉ 14.15.28. toggle_electric() ΓòÉΓòÉΓòÉ

toggle_electric()   PEL

Purpose: Toggles template expansion on or off.

____________

Syntax: void toggle_electric([int on])

____________

Description: The toggle_electric() function toggles the state of PREDITOR/2's
code processing package, sometimes called the "electric" package.  This package
provides assistance with programming-language-specific tasks.  These tasks
include construct template and pair matching.

The optional force argument allows you to force the code processing to the
condition you desire.  If the force argument is non-zero (TRUE), this feature
is turned on regardless of its previous condition. If force is zero, this
feature is always turned off.

By default, code processing package is off.  It may, however, be turned on by
the emulation mode you have selected.  The code processing package is described
more fully in Appendix B of Part One of this manual.

This function has a synonym, ╨ÿ.  A very short name has been selected for this
synonym to facilitate its execution interactively.  This is done through
execute_function(), which in standard keymaps is available by pressing the
key.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.15.29. typeof() ΓòÉΓòÉΓòÉ

typeof()   Primitive

Purpose: Reports the data type of a variable in string form.

____________

Syntax: str typeof(any arg)

____________

Description: The typeof() function tells the type or class of variable that has
been provided as the arg argument to the function.  This enables a program to
test a variable before passing it to a function requiring a specific type of
argument.

____________

Value returned: The value returned by the typeof() function is one of the
following descriptive strings:

Descriptive String       Meaning
"int"                    A signed integer using <= 32 bits.
"string"                 A string of up to 8000 characters.
"regular expression"     A string; may contain meta chars.
"array"                  Variable w/subscripted elements.
"fileid"                 A file handle/descriptor.
"bufid"                  A buffer identification number.
"keymapid"               A keymap identification number.
"winid"                  A window identification number.
"functionid"             A function identification number.
"uninitialized"          A variable not yet assigned a type.

When tested for type, markids are identified as integers.  This allows a mark
id to be more readily compared to an integer.


ΓòÉΓòÉΓòÉ 14.16. Resources ΓòÉΓòÉΓòÉ

call_dll
          Calls a function from a DLL.
get_resource_string()
          Retrieves a string stored in a resource file
load_module()
          Loads a DLL into memory.
use_resource_file()
          Sets a new resource dll the default


ΓòÉΓòÉΓòÉ 14.16.1. call_dll() ΓòÉΓòÉΓòÉ

call_dll()

Purpose: Calls a function from a DLL.

____________

Syntax: call_dll (str module, any function, [types, [parm1, ...]])

____________

Arguments: module - the name of the DLL that stores the function

function - either the name of the function or the ordinal number of the
function to call

types - a string containing the types of the return value and each parameter.
The first character defines the type of the return value and each successive
character defines the type of each parameter.

Valid Parameter Types
A - Any pointer
C - Character
L - Long integer
S - Short integer
V - Void (return value only)
Z - Character pointer (string)

Note:  If a parameter is passed without a corresponding character in the types
string, the type is assumed to be either string (Z) or long (L) depending on
the type of PEL variable passed.  The default type of the return value is Void
(V).

____________

Description: The call_dll() function calls a function from a DLL. If the DLL
has not been loaded by load_module() or a previous call to call_dll(), it will
be loaded automatically before the function is called.

____________

Value returned:  The value from the called function is returned.


ΓòÉΓòÉΓòÉ 14.16.2. get_resource_string() ΓòÉΓòÉΓòÉ

get_resource_string()   Primitive

Purpose: Retrieves a string stored in a resource file

____________

Syntax: string get_resource_string(short resid, [string resfile])

____________

Description: The get_resource_string() function retrieves a string stored in a
resource file.  The string must be stored in a resource file as a STRINGTABLE
resource.

The resid argument is the resource id of the string to be loaded.  The string
resource must either reside in the editors executable file or in a resource
DLL.

The resfile argument contains the name of the resource DLL to use to load the
string.

____________

Value returned: The string from the STRINGTABLE is returned.


ΓòÉΓòÉΓòÉ 14.16.3. load_module() ΓòÉΓòÉΓòÉ

load_module.

Purpose: Loads a DLL into memory.

____________

Syntax: load_module (str name)

____________

Arguments: name - the name of the DLL to load.

____________

Description: The load_module() function loads a DLL into memory to enable you
to call functions.

____________

Value returned:  None.


ΓòÉΓòÉΓòÉ 14.16.4. use_resource_file() ΓòÉΓòÉΓòÉ

use_resource_file()   Primitive

Purpose: Sets a new resource dll the default

____________

Syntax: void use_resource_file([string resource_dll])

____________

Description: The use_resource_file() function sets the default resource dll.
The new resource dll is used in all subsequent functions that require resources
to be loaded and do not specify a resource file. The optional resource_dll
argument contains the name of a resource dll to use as the default.  If no
value is specified the executable file is used as the default location of
resources.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.17. Searching ΓòÉΓòÉΓòÉ

The variables and functions used in search and replacement operations allow
specifying either a string or a  as the search pattern.  The regular
expressions supported by PREDITOR/2 are most similar to those used in PEL, the
Toolbox Language, with a few special extensions.  You will find PREDITOR/2's
version of regular expressions presented in the "Regular Expressions" chapter
of the PREDITOR/2 User's Guide.  Some further instructions are required,
however, on using regular expressions in functions.

A regular expression [may be presented as an argument to a function in several
ways.  You may enter a function that contains a regular expression as a command
to SPE's PEL interpreter or you may enter it in the source code of a function
you are going to compile.

context_search()
          To search for the word at the current cursor location
fgrep()
          To grep for a string in files on disk
freplace()
          Replaces all occurrences of a string with a new string.
grep()
          Locate lines containing a string.
grep_auto()
          To perform a grep in the current buffer for the word at the current
          cursor location
gui_find()
          To display the find dialog.
replace()
          Unadorned text pattern replacement function.
replace_again()
          Repeats a previous replace without further prompting.
replace_backward()
          Prompts for parameters, replaces backward in buffer.
replace_forward()
          Prompts for parameters, replaces backward in buffer.
routines()
          Makes menu of subroutines found in the current buffer.
search()
          Unadorned text pattern matching function.
search_again()
          Repeats a previous search without further prompting.
search_backward()
          Prompts for parameters, searches backward in buffer.
search_forward()
          Prompts for parameters and searches forward in buffer.
search_i()
          Searches for matching text as each character is typed.
search_path()
          Searches for a file within a specified location.
string_replace()
          Replace existing strings in the buffer with a replacement string.
string_search()
          Search for a string in the buffer.
symbol_match()
          List functions and variables matching a string.
toggle_search_flags()
          Changes the value of the search_flags variable.
wgrep()
          To perform a grep on all buffers loaded in the editor.
wreplace()
          Searches and replaces across multiple buffers.
wreplace_again()
          Repeats a previous search and replace across buffers without
          prompting.
wroutines()
          Find the routines in all of the opened buffers.
wsearch()
          Text pattern matching across buffers.
wsearch_again()
          Repeats a previous search across buffers without prompting.


ΓòÉΓòÉΓòÉ 14.17.1. context_search() ΓòÉΓòÉΓòÉ

context_search()   PEL

Purpose:  To search for the word at the current cursor location

____________

Syntax:   context_search( )

____________

Arguments:  none

Description: This function provides a convenient short-cut that can save typing
keystrokes.  Simply place the cursor over the word you want to find more
occurances of and call this function through the command dialog or through a
key assignment.

____________

Value returned:  None.


ΓòÉΓòÉΓòÉ 14.17.2. fgrep() ΓòÉΓòÉΓòÉ

fgrep()   PEL

Purpose:  To grep for a string in files on disk

____________

Syntax:   fgrep( str search_for, [str infileToGrep, int recursive] )

____________

Arguments:

o search_for - string to grep for
o infileToGrep - file or files to grep
o recursive - a TRUE value indicates that the fgrep will be recursive

Description: This function will grep through files on disk for a specified
string.  The infileToGrep parameter may contain wildcards and paths delimited
by semicolons.

See also:  grep(), wgrep()

____________

Value returned:  None.


ΓòÉΓòÉΓòÉ 14.17.3. freplace() ΓòÉΓòÉΓòÉ

freplace()

Purpose:  Replaces all occurrences of a string with a new string.

____________

Syntax:  freplace( str srch, str replacement, str listOfFiles, [int recursive])
)

____________

Arguments:

srch - the string to be replaced

replacement - the new string to replace srch

listOfFiles - files to be changed

recursive - a TRUE value indicates that the function will be recursive

____________

Description: The freplace function replaces all occurrences of a string with a
new string in the files you specify.

____________

Example:

freplace ("boat", "rocket", "c:\src\zoom\*.c;c:\sail\*.h*", FALSE)

The example above replaces all occurrences of "boat" with "rocket" in all .C
files in the C:\SRC\ZOOM directory,  and in all of the .H* files in the C:\SAIL
directory.  Because the recursive argument is FALSE, the subdirectories to the
specified directories are not searched and changed.


ΓòÉΓòÉΓòÉ 14.17.4. grep() ΓòÉΓòÉΓòÉ

grep()   PEL

Purpose: Locate lines containing a string.

____________

Syntax:  void grep(str strpat)

____________

Description: The grep() function searches through the current buffer for lines
containing the string specified by the strpat argument. Lines containing
matches are displayed in the form of a menu, allowing the user to select a line
of interest with the arrow keys or mouse.  The user may then move to that line
by pressing the GOTO push button.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.17.5. grep_auto() ΓòÉΓòÉΓòÉ

grep_auto()   PEL

Purpose:  To perform a grep in the current buffer for the word at the current
cursor location

____________

Syntax:   grep_auto( [int numSearchCount, [int allBuffers]] )

____________

Arguments:

o numSearchCount - the maximum number of occurrances to find
o allBuffers   - if TRUE, search all loaded buffers, else, just the current
  buffer

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.17.6. gui_find() ΓòÉΓòÉΓòÉ

gui_find()   PEL

Purpose:  To display the find dialog.

____________

Syntax:   gui_find()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.17.7. replace() ΓòÉΓòÉΓòÉ

replace()   Primitive

Purpose: Unadorned text pattern replacement function.

____________

Syntax: int replace(str pattern, str replacement, int flags)

____________

Description: The replace() function examines the current buffer for one or more
occurrences of text matching the pattern argument.  The pattern may be a
regular expression or a simple string to match, depending upon the value of the
flags argument.  The matching text is replaced with the contents of the
replacement string. The direction of search and other searching parameters are
also controlled by the flags argument.  The position of the cursor at the end
of the search portion of the operation may be controlled through regular
expressions, but by default is placed at the beginning of the matching text.

The values allowed for flags are those that may be represented by a single
byte.  Each bit of the flags byte sets a searching parameter.  The search_flags
variable is normally used as the flags argument if the search parameters
currently in use are acceptable.  A complete description of the meaning given
to the bits of flag may be found under search_flags.

The replacement operation is repeated as dictated by the variable search_count.
If search_count is 1 or 0 the replacement is carried out once.  If search_count
is greater than 1 the operation is repeated that number of times or until it is
unsuccessful.  In any case, the value of search_count is reset to 0 upon
completion.

____________

Value returned: The value returned by replace() is the number of replacements
made.  If no matches are found, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.17.8. replace_again() ΓòÉΓòÉΓòÉ

replace_again()   PEL

Purpose: Repeats a previous replace without further prompting.

____________

Syntax: int replace_again()

____________

Description: The replace_again() function continues a replace operation for the
next occurrence of matching text. It uses the variables replace_pattern,
search_pattern and search_flags as parameters to the operation without
prompting.  These variables usually reflect the parameters of any previous
replace operation but may be modified by user- written programs.

This replace function does not restore the cursor to its original position
after the replacement, but rather leaves the cursor at the position where the
match occurred.

____________

Value returned: The value returned by the replace_again() function is non-zero
(TRUE) if a match was found.  If not, a value of zero (FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.17.9. replace_backward() ΓòÉΓòÉΓòÉ

replace_backward()   PEL

Purpose: Prompts for parameters, replaces backward in buffer.

____________

Syntax: int replace_backward([str pattern [, str replacement]])

____________

Description: The replace_backward() function is designed to be assigned to a
key.  When no arguments are supplied or if the arguments are empty strings, it
prompts the user for the search pattern and the replacement string.  If there
have been any previous search or replacement operations, the patterns used in
those operations are presented to the user for editing.

If an argument other than an empty string is supplied the user is not prompted
for that argument.  If both arguments are supplied and neither is an empty
string, no prompting occurs. If only one argument is supplied, it is assumed to
be the pattern argument.

Whether or not arguments are supplied,  parameter settings from the prior
search or replace are used. If there were no such prior operations, the
settings found in search_flags are used.

This replace function restores the cursor to its original position after the
replacement rather than leaving the cursor at the position where the match
occurred.

This function resets the SEARCH_FORWARD bit of the search_flags variable.  Thus
it always searches the buffer for matches beginning with the text preceding the
cursor position.

____________

Value returned: The value returned by the replace_backward() function is
non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is
returned.


ΓòÉΓòÉΓòÉ 14.17.10. replace_forward() ΓòÉΓòÉΓòÉ

replace_forward()   PEL

Purpose: Prompts for parameters, replaces backward in buffer.

____________

Syntax: int replace_forward([str pattern [, str replacement]])

____________

Description: The replace_forward() function is designed to be assigned to a
key.  When no arguments are supplied or if the arguments are empty strings, it
prompts the user for the search pattern and the replacement string.  If there
have been any previous search or replacement operations, the patterns used in
those operations are presented to the user for editing.

If an argument other than an empty string is supplied the user is not prompted
for that argument.  If both arguments are supplied and neither is an empty
string, no prompting occurs. If only one argument is supplied, it is assumed to
be the pattern argument.

Whether or not arguments are supplied,  parameter settings from the prior
search or replace are used. If there were no such prior operations, the
settings found in search_flags are used.

This replace function restores the cursor to its original position after the
replacement rather than leaving the cursor at the position where the match
occurred.

This function sets the SEARCH_FORWARD bit of the search_flags variable.  Thus
it always searches the buffer for matches beginning with the text following the
cursor position.

____________

Value returned: The value returned by the replace_forward() function is
non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is
returned.


ΓòÉΓòÉΓòÉ 14.17.11. routines() ΓòÉΓòÉΓòÉ

routines()   PEL

Purpose: Makes menu of subroutines found in the current buffer.

____________

Syntax: void routines()

____________

Description: The routines() function scans the current buffer for subroutines
(functions) and places them in a menu-like list.  The arrow keys or mouse may
then be used to select a subroutine of interest.  The user may then move
directly to that subroutine by pressing  . *  This function operates on .PEL
and .C files only.

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.17.12. search() ΓòÉΓòÉΓòÉ

search()   Primitive

Purpose: Unadorned text pattern matching function.

____________

Syntax: int search(str pattern, int flags)

____________

Description: The search() function examines the current buffer for one or more
occurrences of text matching the pattern argument.  The pattern may be a
regular expression or a simple string to match, depending upon the condition of
the flags variable.  The direction of search and other searching parameters are
also controlled by the flags argument.  The position of the cursor at the end
of the search may be controlled through regular expressions, but by default is
placed at the beginning of the matching text.

The values allowed for flags are those that may be represented by a single
byte.  Each bit of the flags byte sets a searching parameter.  The search_flags
variable is normally used as the flags argument if the search parameters
currently in use are acceptable.  A complete description of the meaning given
to the bits of flag may be found under search_flags

The search operation is repeated as dictated by the variable search_count  If
search_count is 1 or 0 the search is carried out once.  If search_count is
greater than 1 the operation is repeated that number of times or until it is
unsuccessful.  In any case, the value of search_count is reset to 0 upon
completion.

____________

Value returned: The value returned by search() is the number of matches found.
This will normally be one.  If no matches are found, a zero value is returned.

____________

See also:  search_again(), search_forward(), search_backward(), search_i()


ΓòÉΓòÉΓòÉ 14.17.13. search_again() ΓòÉΓòÉΓòÉ

search_again()   PEL

Purpose: Repeats a previous search without further prompting.

____________

Syntax: int search_again()

____________

Description: The search_again() function continues a search for the next
occurrence of matching text.  It uses the variables search_pattern and
search_flags as parameters to the operation without prompting. These variables
usually reflect the parameters of any previous search operation but may be
modified by user-written programs.

____________

Value returned: The value returned by the search_again() function is non-zero
(TRUE) if a match was found.  If not, a value of zero (FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.17.14. search_backward() ΓòÉΓòÉΓòÉ

search_backward()   PEL

Purpose: Prompts for parameters, searches backward in buffer.

____________

Syntax: int search_backward([str pattern])

____________

Description: The search_backward() function is designed to be assigned to a
key.  It prompts the user for the search string when the pattern argument is
not specified.  If there have been any previous searches, the search string
used in the preceding search is presented to the user for editing.  If the
pattern string is supplied no prompting occurs. In either case, the function
then searches the buffer for matches beginning with the text preceding the
cursor position.

The search parameter settings from the prior search are also used.  If there
was no prior search, the settings found in search_flags are used.  This
function resets the SEARCH_FORWARD bit of the search_flags variable.

____________

Value returned: The value returned by the search_backward() function is
non-zero (TRUE) if a match was found. If not, a value of zero (FALSE) is
returned.


ΓòÉΓòÉΓòÉ 14.17.15. search_forward() ΓòÉΓòÉΓòÉ

search_forward()   PEL

Purpose: Prompts for parameters and searches forward in buffer.

____________

Syntax: int search_forward([str pattern])

____________

Description: The search_forward() function is designed to be assigned to a key.
It prompts the user for the search string when the pattern argument is not
specified.  If there have been any previous searches, the search string used in
the preceding search is presented to the user for editing.  If the pattern
string is supplied no prompting occurs. In either case, the function then
searches the buffer for matches beginning with the text following the cursor
position.

The search parameter settings from the prior search are also used.  If there
was no prior search, the settings found in search_flags are used.  This
function sets the SEARCH_FORWARD bit of the search_flags variable.

____________

Value returned: The value returned by the search_forward() function is non-zero
(TRUE) if a match was found.  If not, a value of zero (FALSE) is returned.


ΓòÉΓòÉΓòÉ 14.17.16. search_i() ΓòÉΓòÉΓòÉ

search_i()   PEL

Purpose: Searches for matching text as each character is typed.

____________

Syntax: void search_i()

____________

Description: The search_i() function performs an incremental search in the
current buffer.  In this case, the term incremental means that the search is
performed as each character of the search string is typed in interactively.
This ensures that the minimum number of keystrokes are typed to obtain the
desired match.

This type of search will be familiar to users of the EMACS editor.  For others,
a simple example illustrates the use of this function.  You have a file
containing the following words:

  fast

  after

  ftime

With the cursor at the beginning of the file, you invoke the search_i()
function.  The function prompts you for the search string.  To search for the
word "ftime" you would begin by typing the letter "f".  Without waiting for
further input, the function begins searching for this letter.  The cursor
immediately moves to the first letter of the word "fast".  As you type the
second letter, "t", the cursor moves to the first occurrence of the letters
"ft" which is in the word "after".  As soon as you type the third letter, "i",
the cursor moves to the beginning of the word "ftime".  Since this word is the
subject of your search, no further typing is required.  You then press the
escape key to terminate search_i().

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.17.17. search_path() ΓòÉΓòÉΓòÉ

search_path()

Purpose:  Searches for a file within a specified location.

____________

Syntax:  void search_path(str filename, str srchstring, [long flag])

____________

Arguments:

filename - the file to search for

srchstring - the path or environment variable to search

flag - if srchstring contains a path to search separated by a semicolon, set
this value to 1.  Otherwise, srchstring is considered to be an environment
variable to search.

____________

Description: The search_path() function searches for the given file name in the
given srchstring argument.

____________ Control structures, examples To search for TEXT.TXT in your PATH
environment variable, you would enter:

fullpath = search_path("TEXT.TXT", "PATH")

____________

Value returned: If found, the fully qualified path is returned.  An empty
string ("") is returned if the path is not found.


ΓòÉΓòÉΓòÉ 14.17.18. string_replace() ΓòÉΓòÉΓòÉ

string_replace()   PEL

Purpose:  Replace existing strings in the buffer with a replacement string.

____________

Syntax:   int string_replace(str srch, str repl)

____________

Arguments:

o srch - search value
o repl - replacement value

Description: The string_replace() function searches the current buffer for
srch. When an occurrence of the search pattern is found, the user is prompted
to replace, skip, or replace global.  If global is selected, the remaining
occurences of srch are replaced with repl.

____________

Value returned: The number of occurences replaced.


ΓòÉΓòÉΓòÉ 14.17.19. string_search() ΓòÉΓòÉΓòÉ

string_search()   PEL

Purpose:  Search for a string in the buffer.

____________

Syntax:   int string_search(str sspatt, [short sflags])

____________

Arguments:

o sspatt - pattern to search for in the buffer
o sflags - search flags

Description: The string_search() function searches for sspatt in the current
buffer.  sflags is used as the search flags if provided.  If not, the current
search_flags are used.

____________

Value returned: Number of occurences found.


ΓòÉΓòÉΓòÉ 14.17.20. symbol_match() ΓòÉΓòÉΓòÉ

symbol_match()   Primitive

Purpose: List functions and variables matching a string.

____________

Syntax: array symbol_match(str symbol_name [, int match_type])

____________

Description: The symbol_match() function compiles a list of functions or
variables whose names begin with the string named by the symbol_name argument.
For example, the function call below returns a list of all functions and
variables that begin with the string "toggle_":

func_list = symbol_match("toggle_")

By default, the function lists all functions and variables that match the
string, both primitives (builtins) and those defined in PEL.  The list may be
narrowed or widened to include local functions and variables by specifying the
optional match_type argument. The accepted values for match_type are as
follows:

o ALL_FUN
o ALL_VAR
o GLOBAL_ALL
o GLOBAL_FUN
o GLOBAL_VAR
o LOCAL_ALL
o LOCAL_FUN
o LOCAL_VAR
o PRIMITIVE_ALL
o PRIMITIVE_FUN
o PRIMITIVE_VAR

These values may be combined to receive a list containing symbols of more than
one type.  For example, a value of (ALL_FUN + ALL_VAR) may be used to include
all types of symbols in the list.

____________

Value returned: This function returns an array of strings containing the
matching symbols.  Elements which represent local functions or variables take
the form filename:.symbol_name.


ΓòÉΓòÉΓòÉ 14.17.21. toggle_search_flags() ΓòÉΓòÉΓòÉ

toggle_search_flags()   PEL

Purpose:  Changes the value of the search_flags variable.

____________

Syntax:   toggle_search_flags (long mask, [long value])

____________

Arguments:

o mask - search_flags bit to toggle
o on - forced direction of toggle

Description: toggle_search_flags() changes the state of the bit in search_flags
specified by the mask argument.  If the optional argument, value, is supplied,
the bit changes to that value.  Otherwise the state of the bit toggles.

____________

Value returned:

TRUE  -  mask bit of search_flags was turned on

FALSE -  the bit was turned off

See also: search_flags


ΓòÉΓòÉΓòÉ 14.17.22. wgrep() ΓòÉΓòÉΓòÉ

wgrep()   PEL

Purpose:  To perform a grep on all buffers loaded in the editor.

____________

Syntax:   wgrep( str search_for, [int numSearchCount] )

____________

Arguments:

o search_for   -  the string to grep for
o numSearchCount -  the maximum number of occurances to find

Description:

See also:  grep(), fgrep()

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.17.23. wreplace() ΓòÉΓòÉΓòÉ

wreplace()   PEL

Purpose:  Searches and replaces across multiple buffers.

____________

Syntax:  int wreplace(str srch, str replacement)

____________

Arguments:

srch - string to replace.

replacement - new string to replace srch

____________

Description: The wreplace() function examines all edit buffers for one or more
occurences of text matching the srch argument, and replaces these occurrences
with the replacement argument.

____________

Value returned: None.

____________

See also:  wreplace_again()


ΓòÉΓòÉΓòÉ 14.17.24. wreplace_again() ΓòÉΓòÉΓòÉ

wreplace_again()   PEL

Purpose:  Repeats a previous search and replace across buffers without
prompting.

____________

Syntax:  int wreplace_again()

____________

Description: The wreplace_again() function continues a search and changes the
next occurrence of matching text.  This function is simply a repeat of the most
recent wreplace() function call.

____________

Value returned:  None.


ΓòÉΓòÉΓòÉ 14.17.25. wroutines() ΓòÉΓòÉΓòÉ

wroutines()   PEL

Purpose:  Find the routines in all of the opened buffers.

____________

Syntax:   void wroutines()

____________

Arguments: none.

Description: The wroutines() function searches all of the buffers in the buffer
list to find the functions defined in them.  The resulting list is displayed in
a list box.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.17.26. wsearch() ΓòÉΓòÉΓòÉ

wsearch()   PEL

Purpose: Text pattern matching across buffers.

____________

Syntax: int wsearch(str pattern, int flags)

____________

Description: The wsearch() function examines all edit buffers for one or more
occurrences of text matching the pattern argument.  It is similar to the
search() function, which searches only the current buffer.

The pattern may be a regular expression or a simple string to match, depending
upon the condition of the flags variable.  The direction of search and other
searching parameters are also controlled by the flags argument.  The position
of the cursor at the end of the search may be controlled through regular
expressions, but by default is placed at the beginning of the matching text.

The values allowed for flags are those that may be represented by a single
byte.  Each bit of the flags byte sets a searching parameter.  The search_flags
variable is normally used as the flags argument if the search parameters
currently in use are acceptable.  A complete description of the meaning given
to the bits of flag may be found under search_flags.

The search operation is repeated as dictated by the variable search_count.  If
search_count is 1 or 0 the search is carried out once.  If search_count is
greater than 1 the operation is repeated that number of times or until it is
unsuccessful.  In any case, the value of search_count is reset to 0 upon
completion.

____________

Value returned: The value returned by wsearch() is the number of matches found.
This will normally be one.  If no matches are found, a zero value is returned.


ΓòÉΓòÉΓòÉ 14.17.27. wsearch_again() ΓòÉΓòÉΓòÉ

wsearch_again()   PEL

Purpose: Repeats a previous search across buffers without prompting.

____________

Syntax: int wsearch_again()

____________

Description: The wsearch_again() function continues a search for the next
occurrence of matching text.  This function is similar to the search_again()
function, which searches only the current buffer.  It uses the variables
search_pattern and search_flags as parameters to the operation without
prompting.

These variables usually reflect the parameters of any previous search operation
but may be modified by user-written programs.

____________

Value returned: The value returned by the wsearch_again() function is non-zero
(TRUE) if a match was found.  If not, a value of zero (FALSE) is returned


ΓòÉΓòÉΓòÉ 14.18. String Manipulation ΓòÉΓòÉΓòÉ

The functions in the String Manipulation category provide the capabilities to
locate strings or convert them from one form to another.  There are functions
to locate or change substrings, to determine if a character is numeric or
punctuation, and functions to translate one character to another.

There are several functions that manipulate the case of  in the strings
provided to them as arguments.  These functions are toupper(), tolower() and
toreverse().  There are several similar functions in the Word Processing
category that perform the corresponding service on a marked block of text
rather than a string.  They have been similarly named upper(), lower() and
reverse().

The sub() and gsub() functions are unique in AWK in that they modify the string
argument you give it.  Other functions return the modified string or value but
never modify an argument.  gsub() instead returns the number of substitutions
it made within the supplied string.

atoi()
          Convert an ASCII string to an integer.
chr()
          Makes a one character string from an ASCII value.
cindex()
          Reports position of the first occurrence of a character.
compress()
          Deletes multiple occurrences of a character.
gsub()
          Replace occurrences of a substring with another.
index()
          Reports position of the first occurrence of a sub-string.
insert_string()
          Insert a string into current buffer at cursor position.
int_to_ascii()
          Interprets a keycode into the corresponding ASCII value.
isalnum()
          Tells if characters are in the alpha-numeric set.
isalpha()
          Tells if characters are in the alphabetical set.
isascii()
          Tells if characters are in the ASCII set.
iscntrl()
          Tells if characters are in the control character set.
isdigit()
          Tells if characters represent numbers.
isgraph()
          Tells if characters have visible printing representation.
islower()
          Tells if characters are lower-case letters.
isprint()
          Tells if characters have printable representation.
ispunct()
          Tells if characters represent punctuation.
isspace()
          Tells if characters are white-space.
isupper()
          Tells if characters are lower-case letters.
isxdigit()
          Tells if characters represent hexadecimal numbers.
length()
          Tells the length of a specified string.
ltrim()
          Deletes specified characters from beginning of line.
match()
          Returns the position of the first occurrence of a matching string.
ord()
          Casts a one character string as an integer value.
prefix()
          Obtain a sub-string from the beginning of a string.
quote_regex()
          Converts possible metacharacters to literals.
rindex()
          Reports position of the last occurrence of a sub-string.
sprintf()
          Creates a formatted string.
strmax()
          Returns the string with the highest lexical value.
strmin()
          Returns the string with the lowest lexical value.
strrepeat()
          Makes a string by concatenating repetitions of another.
strtok()
          This function parses a string into sub strings delimited by the
          regular expression delimeter specified.
sub()
          Replace first occurrence of a substring with another
substr()
          Create a new string from a portion of another string.
suffix()
          Creates a string from the tail of another string.
tolower()
          Converts all letters in a string to lower-case.
toupper()
          Converts all letters in a string to upper-case.
trans()
          Translates characters in one string to those in another.
trim()
          Deletes specified characters from end of line.


ΓòÉΓòÉΓòÉ 14.18.1. atoi() ΓòÉΓòÉΓòÉ

atoi()   Primitive

Purpose: Convert an ASCII string to an integer.

____________

Syntax:  int atoi(str s [, int radix])

____________

Description: The atoi() function converts the s string argument into an
integer.  The numeric portion of the s string may be any value that may be
represented by a 32 bit signed integer (-2,147,483,646 to 2,147,483,647). By
default, the number contained in the string is assumed to be in decimal
notation.  Other notations must be explicitly named by the radix argument.

The values for the radix argument must be in the range of 2 to 16.  Specify 2
for binary, 8 for octal, 10 for decimal or 16 for hexadecimal.  The string may
contain non-numeric characters, but these must follow the numeric portion of
the string. Otherwise the numeric portion will not be converted.

____________

Value returned:

The value returned by the atoi() function is the integer equivalent of the
numeric portion of the string.  A zero value is returned if any non-numeric
character precedes the numeric portion of the string. This includes leading
whitespace.  If radix is not one of the allowed values, it is considered an
error, and a zero value is returned.

____________

Example:

testInt = atoi("329 programmers")

The value of testInt is then 329.


ΓòÉΓòÉΓòÉ 14.18.2. chr() ΓòÉΓòÉΓòÉ

chr()   Primitive

Purpose: Makes a one character string from an ASCII value.

____________

Syntax:  str chr(int num)

____________

Description: The chr() function creates a new string containing a single
character.  The character contained in the string is the character equivalent
of the value in the num argument.

Values for num may be from 0 to 255.  If any other value is supplied, only the
lowest byte is considered.

____________

Value returned:

The value returned by the chr() function is the new one character string.


ΓòÉΓòÉΓòÉ 14.18.3. cindex() ΓòÉΓòÉΓòÉ

cindex()   Primitive

Purpose: Reports position of the first occurrence of a character.

____________

Syntax:  int cindex(str s, str c)

____________

Description: The cindex() function searches the s string argument for
occurrences of the character or characters in the c argument.  The function
then reports the position in the s string at which the character first
occurred.  More than one character may be supplied in the c argument.  When
this is done, the position of whichever character of c occurs in s first is
reported.

This function differs from index() in that it considers c as a series of
characters rather than as a sub-string.

____________

Value returned:

The value returned by the cindex function is the ordinal position of the
"found" character within the string.  If no matches were found, or if one of
the arguments is an empty string, the function returns a zero value.


ΓòÉΓòÉΓòÉ 14.18.4. compress() ΓòÉΓòÉΓòÉ

compress()   PEL

Purpose: Deletes multiple occurrences of a character.

____________

Syntax:  str compress(str s [, str t])

____________

Description: The compress() function creates a new string from the s argument.
The new string is the same as the argument except that all occurrences of the
characters in the t argument are reduced to a single occurrence of the first
character of t.  Sequential occurrences of one or more of the characters of t,
regardless of order, are likewise compressed to one occurrence of the t
argument's first character.

This function is intended primarily as a method of "collapsing" white space.
For this reason, if the t argument is not specified, this function will
compress occurrences of tabs and spaces into single occurrences of spaces.
This action is the same as if the string " \t" (space followed by tab) were
provided as the t argument.

____________

Value returned:

The value returned by the compress function is the newly compressed string.

____________

Examples:


  compress("THIS     that")

  returns:  "THIS that"


and:


  compress("EDCBA","ABCDE")

  returns:  "A"


ΓòÉΓòÉΓòÉ 14.18.5. gsub() ΓòÉΓòÉΓòÉ

gsub()   Primitive

Purpose: Replace occurrences of a substring with another.

____________

Syntax:  int gsub(str regex, str repl, str s)

____________

Description: The gsub() function substitutes the specified replacement string,
repl, for substrings matching the regex argument within the string S.  The
regex argument is a regular expression.

The special characters that may be used in the regex argument are those
described in the "Regular Expressions" chapter of the User's Manual.  These
characters may be used without regard to the state of the search_flags
variable.  The scope of the match is always maximal.

____________

Value returned:

The value returned by the gsub() variable is the number of replacements made.
If any of the arguments is an empty string, the function will return an empty
string.

____________

See also:  sub()


ΓòÉΓòÉΓòÉ 14.18.6. index() ΓòÉΓòÉΓòÉ

index()   Primitive

Purpose: Reports position of the first occurrence of a sub-string.

____________

Syntax:  int index(str s, str sub)

____________

Description: The index() function searches the s string argument for the first
occurrence of the sub-string in the sub argument.  The function then reports
the position in the s string at which the sub-string occurred. This function
differs from cindex() in that it considers sub as a sub-string rather than a
series of characters.

____________

Value returned:

The value returned by the index() function is the ordinal position at which the
sub- string begins.  If no matches were found, or if one of the arguments was
not a valid string, the function returns a zero value.

____________

See also:  rindex()


ΓòÉΓòÉΓòÉ 14.18.7. insert_string() ΓòÉΓòÉΓòÉ

insert_string()   Primitive

Purpose: Insert a string into current buffer at cursor position.

____________

Syntax:  str insert_string(str string)

____________

Description: The insert_string() function incorporates a string specified by
the string argument into the current buffer at the current cursor position.
After the insertion, the cursor is positioned at the end of the inserted
string.  The included string may contain new lines and tabs, as desired. New
lines found in the string are converted to conform to the buffer_eol_string
currently in effect.

The primary use of this function is to insert boilerplate text into the buffer.
For example, this function might be used to add text specific to a certain
programming language, such as control structures.

____________

Value returned:

This function returns the inserted string or an empty string if the supplied
string was empty.


ΓòÉΓòÉΓòÉ 14.18.8. int_to_ascii() ΓòÉΓòÉΓòÉ

int_to_ascii()   Primitive

Purpose: Interprets a keycode into the corresponding ASCII value.

____________

Syntax:  int int_to_ascii(int char)

____________

Description: The int_to_ascii() function provides the ASCII character
corresponding to the key described by the char argument.  The char argument is
a keycode value such as that returned by the getkey() or getchar() keyboard
input functions.

____________

Value returned:

The value returned by the int_to_ascii() function is the key's ASCII value.


ΓòÉΓòÉΓòÉ 14.18.9. isalnum() ΓòÉΓòÉΓòÉ

isalnum()   Primitive

Purpose: Tells if characters are in the alpha-numeric set.

____________

Syntax:  int isalnum(str s)

____________

Description: The isalnum() function tests the characters in the s argument
string to determine if they are alpha-numeric characters.  Alpha- numeric
characters include upper-case characters (A - Z), lower-case characters (a - z)
and numeric characters (0 - 9).

____________

Value returned:

When all the characters in the argument string are within the definition of
alpha- numeric characters, the isalnum() function returns a non-zero value
(TRUE).  If any of the characters are other than alpha- numeric, the function
returns zero (FALSE).


ΓòÉΓòÉΓòÉ 14.18.10. isalpha() ΓòÉΓòÉΓòÉ

isalpha()   Primitive

Purpose: Tells if characters are in the alphabetical set.

____________

Syntax:  int isalpha(str s)

____________

Description: The isalpha() function tests the characters in the s argument
string to determine if they characters of the alphabet.  This includes
upper-case characters (A - Z) and lower-case characters (a - z).

____________

Value returned:

When all the characters in the argument string are letters in (A - Z) or (a -
z), the isalpha() function returns a non-zero value.  If any of the characters
are not letters of the alphabet, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.11. isascii() ΓòÉΓòÉΓòÉ

isascii()   Primitive

Purpose: Tells if characters are in the ASCII set.

____________

Syntax:  int isascii(str s)

____________

Description: The isascii() function tests the characters in the s argument
string to determine if the character corresponds to an ASCII value.  This
includes characters with values from 0 to 127.

____________

Value returned:

When all the characters in the argument string have a corresponding ASCII
value, the isascii() function returns a non-zero value.  If any of the
characters are not ASCII, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.12. iscntrl() ΓòÉΓòÉΓòÉ

iscntrl()   Primitive

Purpose: Tells if characters are in the control character set.

____________

Syntax:  int iscntrl(str s)

____________

Description: The iscntrl() function tests the characters in the s argument
string to determine if their value corresponds to a control character.  Control
characters are those with an ASCII value between 0 and 31, and 127, the delete
character.

____________

Value returned:

When all the characters in the argument string are control characters, the
iscntrl() function returns a non-zero value.  If any of the characters is not a
control character, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.13. isdigit() ΓòÉΓòÉΓòÉ

isdigit()   Primitive

Purpose: Tells if characters represent numbers.

____________

Syntax:  int isdigit(str s)

____________

Description: The isdigit() function tests the characters in the s argument
string to determine if they are an ASCII representation of a digit.  A
character is deemed to be a digit if it is in the set of 0 to 9.

____________

Value returned:

When all the characters in the argument string are digits, the isdigit()
function returns a non-zero value.  If any of the characters does not represent
a numeral, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.14. isgraph() ΓòÉΓòÉΓòÉ

isgraph()   Primitive

Purpose: Tells if characters have visible printing representation.

____________

Syntax:  int isgraph(str s)

____________

Description: The isgraph() function tests the characters in the s argument
string to determine if they are printing characters.  The isgraph() function
does not consider the space a printing character, as the isprint() function
does.  A character is deemed graphic if its ASCII value is within the range of
33 to 126.

____________

Value returned:

When all the characters in the argument string are printable, the isgraph()
function returns a non-zero value.  If any of the characters is non-printable
or is a space, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.15. islower() ΓòÉΓòÉΓòÉ

islower()   Primitive

Purpose: Tells if characters are lower-case letters.

____________

Syntax:  int islower(str s)

____________

Description: The islower() function tests the characters in the s argument
string to determine if they are lower-case letters.  The characters a to z are
considered lower- case.

____________

Value returned:

When all the characters in the argument string are lower-case, the islower()
function returns a non-zero value.  If the string contains any characters that
are not lower-case, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.16. isprint() ΓòÉΓòÉΓòÉ

isprint()   Primitive

Purpose: Tells if characters have printable representation.

____________

Syntax:  int isprint(str s)

____________

Description: The isprint() function tests the characters in the s argument
string to determine if they are printing characters.  The isprint() function
considers the space a printing character, whereas the isgraph() function does
not.  A character is deemed printable if its ASCII value is within the range of
32 to 126.

____________

Value returned:

When all the characters in the argument string are printable, the isprint()
function returns a non-zero value.  If the string contains any characters that
are not printable, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.17. ispunct() ΓòÉΓòÉΓòÉ

ispunct()   Primitive

Purpose: Tells if characters represent punctuation.

____________

Syntax:  int ispunct(str s)

____________

Description: The ispunct() function tests the characters in the s argument
string to determine if they are punctuation.  A character is deemed to be
punctuation if its ASCII value falls in any of the following ranges:  33 - 47,
58 - 64, 91 - 96, 123 - 126.

____________

Value returned:

When all the characters in the argument string are punctuation, the ispunct()
function returns a non-zero value.  If any of the characters does not represent
punctuation, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.18. isspace() ΓòÉΓòÉΓòÉ

isspace()   Primitive

Purpose: Tells if characters are white-space.

____________

Syntax:  int isspace(str s)

____________

Description: The isspace() function tests the characters in the s argument
string to determine if they are white-space characters.  White- space
characters are defined as space, tab, carriage return, line feed, form feed and
vertical tab.  The ASCII values of these characters are described by the set 9
to 13 and 32.

____________

Value returned:

When all the characters in the argument string are white-space, the isspace()
function returns a non-zero value.  If any of the characters does not represent
white- space, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.19. isupper() ΓòÉΓòÉΓòÉ

isupper()   Primitive

Purpose: Tells if characters are lower-case letters.

____________

Syntax:  int isupper(str s)

____________

Description: The isupper() function tests the characters in the s argument
string to determine if they are upper-case letters.  The characters A to Z are
considered upper- case.

____________

Value returned:

When all the characters in the argument string are upper-case, the isupper()
function returns a non-zero value.  If the string contains any characters that
are not upper-case, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.20. isxdigit() ΓòÉΓòÉΓòÉ

isxdigit()   Primitive

Purpose: Tells if characters represent hexadecimal numbers.

____________

Syntax:  int isxdigit(str s)

____________

Description: The isxdigit() function tests the characters in the s argument
string to determine if they are an ASCII representation of a hexadecimal digit.
A character is deemed to be a hexadecimal digit if it is in the set of 0 to 9
and either A to F or a to f.

____________

Value returned:

When all the characters in the argument string are hexadecimal digits, the
isxdigit() function returns a non-zero value.  If any of the characters does
not represent a hexadecimal number, the function returns zero.


ΓòÉΓòÉΓòÉ 14.18.21. length() ΓòÉΓòÉΓòÉ

length()   Primitive

Purpose: Tells the length of a specified string.

____________

Syntax: int length(str s)

____________

Description: The length() function reports the length of the s argument string.

____________

Value returned: The value returned by length is the number of characters in the
string.  If the s argument does not represent a defined string, the length will
be reported as 0.

____________ Compatibility: This function is used in the same manner as the
like-named AWK function.


ΓòÉΓòÉΓòÉ 14.18.22. ltrim() ΓòÉΓòÉΓòÉ

ltrim()   PEL

Purpose: Deletes specified characters from beginning of line.

____________

Syntax: str ltrim(str s [, str t])

____________

Description: The ltrim() function creates a new string from the s argument, in
which the characters in the t argument have been stripped from the left side of
the string.  The new string will not begin with any of the characters specified
by t.

If the t argument is omitted, all white-space will be stripped from the left
end of the line.  For the purpose of this function, white-space is defined as
spaces and tabs.

____________

Value returned: The value returned by the ltrim() function is the newly created
string.

See also: trim()


ΓòÉΓòÉΓòÉ 14.18.23. match() ΓòÉΓòÉΓòÉ

match()   Primitive

Purpose: Returns the position of the first occurrence of a matching string.

____________

Syntax: int match(str s, str regex, [int ignoreCase])

____________

Description: The match() function searches the s argument for the first
occurrence of text matching the regex argument.  The function then reports the
position in the s string at which the match occurred.

The regex argument is a regular expression, using the special characters
defined for regular expressions.  These characters are described in the
"Regular Expressions" chapter of the PREDITOR/2 User's Guide. The special
meaning of these characters is in effect without regard to the state of the
search_flags variable.  The scope of the match is always maximal.

By default, match() is case sensitive.  If you specify the ignoreCase argument
to 1, the match() function will be case insensitive.

____________

Value returned: The value returned by the match() function is the ordinal
position at which the matching text begins. If no matches were found, or if one
of the arguments was not a valid string, the function returns a zero value.

____________

See also: RSTART, RLENGTH


ΓòÉΓòÉΓòÉ 14.18.24. ord() ΓòÉΓòÉΓòÉ

ord()   Primitive

Purpose: Casts a one character string as an integer value.

____________

Syntax: int ord(str s)

____________

Description: The ord() function reports the ASCII value of the character in the
s string argument.  If the string argument contains more than one character,
only the first character will be considered.

____________

Value returned: The value returned by the ord() function is the ASCII value
corresponding to the first character of the s argument.  If the string is empty
or has not been defined, the function will return a zero value.


ΓòÉΓòÉΓòÉ 14.18.25. prefix() ΓòÉΓòÉΓòÉ

prefix()   Primitive

Purpose: Obtain a sub-string from the beginning of a string.

____________

Syntax: str prefix(str s, int num)

____________

Description: The prefix() function creates a new string which is a sub-string
of the s argument.  The sub-string is copied from the beginning of the string
argument. The number of characters copied into the new string is determined by
the value of the num argument.

____________

Value returned: The value returned by the prefix() function is the newly
created string.  If the num argument is greater than the length of the string,
the entire string is returned.  If the supplied string is empty, an empty
string is returned.


ΓòÉΓòÉΓòÉ 14.18.26. quote_regex() ΓòÉΓòÉΓòÉ

quote_regex()   PEL

Purpose: Converts possible metacharacters to literals.

____________

Syntax: str quote_regex(str s)

____________

Description: The quote_regex() function creates a new string based on the one
provided in the s argument.  The new string is identical to the argument except
that a backslash precedes each character that has special meaning in regular
expressions.  These characters, called metacharacters, are described in the
"Regular Expressions" chapter of the User's Manual.  The preceding backslash
ensures that these characters will not be given special meaning.

This function is useful when you wish to search for an ordinary string which is
to used as part of a larger regular expression.

____________

Value returned: The value returned by the quote_regex() function is the newly
created string.


ΓòÉΓòÉΓòÉ 14.18.27. rindex() ΓòÉΓòÉΓòÉ

rindex()   Primitive

Purpose: Reports position of the last occurrence of a sub-string.

____________

Syntax: int rindex(str s, str sub)

____________

Description: The rindex() function searches the s string argument for the
right-most occurrence of the sub- string in the sub argument.  The function
then reports the position in the s string at which the sub-string occurred.

____________

Value returned: The value returned by the rindex() function is the ordinal
position at which the sub-string begins. If no matches were found, or if one of
the arguments was not a valid string, the function returns a zero value.

____________

See also:  index()


ΓòÉΓòÉΓòÉ 14.18.28. sprintf() ΓòÉΓòÉΓòÉ

sprintf()   Primitive

Purpose: Creates a formatted string.

____________

Syntax: str sprintf(str fmt [, any args,...])

____________

Description: The sprintf() function creates a string, formatted as indicated by
the fmt and args arguments.

The fmt string argument may contain both text to be printed literally and
format control characters. Format control characters specify how the args
arguments are to be formatted and included in the output string.  These format
control characters are described under the fprintf() function.

____________

Value returned:

The sprintf() function returns the newly created string on successful
completion.  Upon failure, normally due to incorrectly formed arguments, the
function returns an empty string.


ΓòÉΓòÉΓòÉ 14.18.29. strmax() ΓòÉΓòÉΓòÉ

strmax()   Primitive

Purpose: Returns the string with the highest lexical value.

____________

Syntax: str strmax(str s1 [, str s2 ...])

____________

Description: The strmax() function creates a new string that is a copy of the
argument string having the greatest lexical value.  This function is useful
primarily in sorting.  The following examples will clarify:

  strmax("cat","dog")
   returns "dog".

  strmax("xxxx","XXXX")
   returns "xxxx".

  strmax("20","100")
   returns "20".

  strmax("AAA","AAAA")
   returns "AAAA".

____________

Value returned: Upon successful completion, strmax() returns the new string.


ΓòÉΓòÉΓòÉ 14.18.30. strmin() ΓòÉΓòÉΓòÉ

strmin()   Primitive

Purpose: Returns the string with the lowest lexical value.

____________

Syntax: str strmin(str s1 [, str s2 ...])

____________

Description: The strmin() function creates a new string that is a copy of the
argument string having the lowest lexical value.  This function is primarily
useful in sorting.  For examples see the strmax() function above.  In each case
strmin() would return the opposite argument to that returned by strmax().

____________

Value returned: Upon successful completion, strmin() returns the new string.


ΓòÉΓòÉΓòÉ 14.18.31. strrepeat() ΓòÉΓòÉΓòÉ

strrepeat()   PEL

Purpose: Makes a string by concatenating repetitions of another.

____________

Syntax: str strrepeat(str s, int num)

____________

Description: The strrepeat() function creates a new string containing
repetitions of the string indicated by the s  argument.  The number of
repetitions contained in the new string is determined by the value of the num
argument.

____________

Value returned: The value returned by the strrepeat() function is the newly
defined string.


ΓòÉΓòÉΓòÉ 14.18.32. strtok() ΓòÉΓòÉΓòÉ

strtok()   PEL

Purpose:  This function parses a string into sub strings delimited by the
regular expression delimeter specified.

____________

Syntax:   strtok( str to_parse, regex delimeter )

____________

Arguments:

o to_parse  - the string to parse
o delimeter - the regex delimeter of the sub-strings in str

Description: This function works similarly to the C function strtok(), but not
identically.  The first call to strtok() includes the parameters to_parse and
delimeter, and returns the first sub-string in to_parse.  Sub-sequent calls to
strtok() provide no parameters, and return the subsequent sub-strings in
to_parse.  When no more sub-strings can be found in to_parse, strtok() returns
"". For example, to parse the string "one, two, three, four" using strtok():
str    = "one, two, three, four" substr  = strtok( str, "[, ]+" )  # delimit by
>= 1 commas # or spaces  do message( substr ) while ( (substr = strtok()) )
The above code would displays messages for each of the four strings delimited
by commas or spaces in str.

____________

Value returned:  The next sub-string, or "" if no more sub-strings


ΓòÉΓòÉΓòÉ 14.18.33. sub() ΓòÉΓòÉΓòÉ

sub()   Primitive

Purpose: Replace first occurrence of a substring with another

____________

Syntax: int sub(str regex, str repl, str s)

____________

Description: The sub() function substitutes the specified replacement string,
repl, for the left-most substring matching the regex argument within string S.
The regex argument is a regular expression.

The special characters that may be used in the regex argument are those defined
for regular expressions.  These characters are described in the "Regular
Expressions" chapter of the User's Manual. The special meaning of these
characters may be used without regard to the state of the search_flags
variable.  The scope of the match is always maximal.

____________

Value returned: The value returned by the sub() variable is one (TRUE) if a
match was found.  The function returns zero (FALSE) if no match was found.


ΓòÉΓòÉΓòÉ 14.18.34. substr() ΓòÉΓòÉΓòÉ

substr()   Primitive

Purpose: Create a new string from a portion of another string.

____________

Syntax: str substr(str s, int pos [, int count])

____________

Description: The substr() function creates a string by making a copy of a
portion of the s argument.  Characters are copied into the new string starting
with the character indicated by the pos argument.  The pos argument describes
the ordinal position of the starting character within the string.

The count argument tells the number of characters to be copied.  If this number
exceeds the number of characters available for copying, all available
characters are copied into the new string.  If the count argument is omitted,
the remainder of the string is copied beginning at the pos position.

____________

Value returned: Upon successful completion, the substr() function returns the
newly created string.  If an empty string or negative number has been provided
as an argument, the function returns an empty string.


ΓòÉΓòÉΓòÉ 14.18.35. suffix() ΓòÉΓòÉΓòÉ

suffix()   Primitive

Purpose: Creates a string from the tail of another string.

____________

Syntax: str suffix(str s, int count)

____________

Description: The suffix() function creates a string by making a copy of a
portion of the s argument.  The number of characters copied into the new string
is indicated by the count argument.  Count characters are copied from the end
of the s string to the new string.

____________

Value returned: Upon successful completion, the suffix() function returns the
newly created string.  If an empty string or negative number has been provided
as an argument, the function returns an empty string.


ΓòÉΓòÉΓòÉ 14.18.36. tolower() ΓòÉΓòÉΓòÉ

tolower()   Primitive

Purpose: Converts all letters in a string to lower-case.

____________

Syntax: str tolower(str s)

____________

Description: The tolower() function creates a new string from the s argument in
which all upper-case letters have been converted to lower-case.  The numbers
punctuation and white-space in the string are not modified by this function.

____________

Value returned: The value returned by the tolower() function is the newly
created string.  If the argument represents an empty string, the function will
return an empty string.


ΓòÉΓòÉΓòÉ 14.18.37. toupper() ΓòÉΓòÉΓòÉ

toupper()   Primitive

Purpose: Converts all letters in a string to upper-case.

____________

Syntax: str toupper(str s)

____________

Description: The toupper() function creates a new string from the s argument in
which all lower-case letters have been converted to upper-case.  The numbers
punctuation and white-space in the string are not modified by this function.

____________

Value returned: The value returned by the toupper() function is the newly
created string.  If the argument represents an empty string, the function will
return an empty string.


ΓòÉΓòÉΓòÉ 14.18.38. trans() ΓòÉΓòÉΓòÉ

trans()   PEL

Purpose: Translates characters in one string to those in another.

____________

Syntax: str trans(str s, str tr, str repl)

____________

Description: The trans() function creates a new string, translating individual
characters of one string to those found in another.  For those familiar with
the UNIX_ operating environment, this function works similarly to the "tr"
command found in that environment. Each character in the s argument is compared
to the characters in tr.  If a character in s matches the character at position
n of tr, it is replaced by character n of repl.  If the tr string is longer
than the repl string, there will be some characters in tr that have no
corresponding character in the repl argument.  In these cases, the character in
tr is deleted from the s string when creating the new string.

____________

Value returned: The value returned by the trans() function is the newly created
string.  If the first or second argument supplied to this function is an empty
string, the function will fail and an empty string is returned.


ΓòÉΓòÉΓòÉ 14.18.39. trim() ΓòÉΓòÉΓòÉ

trim()   PEL

Purpose: Deletes specified characters from end of line.

____________

Syntax: str trim(str s [, str t])

____________

Description: The trim() function creates a new string from the s argument, in
which the characters in the t argument have been stripped from the right side
of the string.  The new string will not end with any of the characters
specified by t.

If the t argument is omitted, all white-space will be stripped from the right
end of the line.  For the purpose of this function, white-space is defined as
spaces and tabs.

____________

Value returned: The value returned by the trim() function is the newly created
string.  If any of the arguments do not represent a defined string, the
function will return an empty string.


ΓòÉΓòÉΓòÉ 14.19. System Interface ΓòÉΓòÉΓòÉ

The variables and functions in the System Interface category provide for low
level file input/output and other useful DOS services.  In addition, this
category contains a few higher level file-handling utilities, such as f
ilecopy() and filemove().

Many of these functions are similar, if not identical, to functions provided by
the major  compilers.  For this reason the issue of compatibility with similar
functions is addressed in the complete description of these functions. These
complete descriptions may be found in the Library Reference Manual.

The area where PREDITOR/2 functions most commonly deviate from their C
counterparts is that of return value.  PREDITOR/2 functions adhere to a
convention of returning a non-zero value on success and a zero value on
failure, whenever reasonable. The errno variable provides further information
when errors occur.

The file handles provided as variables here allow access to the standard
devices.  Such devices as stdout and stderr may be redirected or even closed
without affecting editor operations.

abort()
          Terminate the editing session abnormally.
bld_fnam()
          To build a fully qualified path out of its components
buildpath()
          Creates an absolute path from a partial or relative one.
chdir()
          Set the default directory.
close_pipes()
          Close the pipes opened by create_pipes()
create_pipes()
          Opens I/O pipes to communicate with other programs
create_temp_name()
          Creates a string containing a unique filename.
disk_free()
          Reports storage space available on a drive.
dos_box()
          Execute system commands from within the editor.
dos_drive()
          Obtain or set the current drive.
dos_verify_state()
          Obtain or set the verify flag.
dos_window()
          Run a command in a window.
editor_path()
          Tells where the editor Home Directory is.
fclose()
          Close the file associated with a handle.
fgetc()
          Gets a character from a file.
fgets()
          To get a string from a file handle.
filecopy()
          File copying utility.
filemode()
          Obtain or set the attributes of a file if it exists.
filemove()
          File moving utility
filesize()
          Determine the size of a file.
filetime()
          Obtain or set the timestamp associated with a file.
filter()
          Processes a portion of a buffer through a command.
findfirst()
          Begin a directory search.
findnext()
          Continue a directory search.
fopen()
          Open a file for processing.
fprintf()
          Writes a formatted string to a device.
fputc()
          Puts a character in a file.
fread()
          Read a portion of a file into the active buffer.
fseek()
          Move the file pointer.
ftell()
          Reports current position of file pointer.
fwrite()
          Write a block of text to a file.
getcwd()
          Obtain the current working directory of a drive.
idle()
          Allows processing of the message queue
mkdir()
          Create a new directory.
path_ext()
          Extract the filename extension from a string.
path_fname()
          Extract a filename from a string.
path_path()
          To return the path portion of a fully qualified path and filename.
pgetc()
          Read a character from a read pipe. Does not return until a character
          is available.
pgets()
          Read a string from an input pipe. Does not return until data is
          available.
pop_dir()
          Makes previously stored directory current.
pputc()
          Write a character into an output pipe.
pputs()
          Write a string into an output pipe.
pread()
          Read a string from an input pipe into the active buffer.
process_pipes()
          Process strings from an input pipe. Issues PIPE_DATA_EVENTs when data
          is available.
push_dir()
          Saves the current directory and logs to new one.
pwd()
          Displays the current working directory
pwrite()
          Write a block of text to an output pipe.
query_pid()
          Query the process id of a pipe.
rename()
          Change the name of a file or series of files.
rmdir()
          Delete a file directory.
spawn()
          Starts a detached process
system()
          Allows command execution without exiting to OS2
system_key()
          Prompts user for operating system command.
unlink()
          Delete a file.
unlock_edit_files()
          Unlocks all files that have been locked.
unlock_file()
          Unlocks a filesthat has been locked.


ΓòÉΓòÉΓòÉ 14.19.1. abort() ΓòÉΓòÉΓòÉ

abort()   Primitive

Purpose: Terminate the editing session abnormally.

____________

Syntax:  void abort([int code])

____________

Description: abort() immediately terminates the editing session, returning
control to the operating system.  Any edits not previously saved are lost.  In
addition, no "clean-up" is attempted and therefore no temporary files are
deleted.

The code argument determines what exit code is returned to the operating
system. Values for code of 255 and greater return an exit code of 255.  If the
code is not supplied, an exit code of three is used.

____________

Value returned:

abort() returns no value since it never returns.

____________

Compatibility:

This function is similar to the ANSI C abort() function except that the exit
code may be specified.


ΓòÉΓòÉΓòÉ 14.19.2. bld_fnam() ΓòÉΓòÉΓòÉ

bld_fnam()   PEL

Purpose:  To build a fully qualified path out of its components

____________

Syntax:   bld_fnam( str path, str name, str ext )

____________

Arguments:

o path   -  path to the file
o name   -  name of the file
o ext    -  extension of the file

Description:

____________

Value returned:  The fully qualified path and filename


ΓòÉΓòÉΓòÉ 14.19.3. buildpath() ΓòÉΓòÉΓòÉ

buildpath()   Primitive

Purpose: Creates an absolute path from a partial or relative one.

____________

Syntax:  str buildpath(str path)

____________

Description: The buildpath() function constructs an explicitly defined path
from the partial or relative path supplied in the path argument.  For example,
if you are currently logged to drive C: and your current working directory is
\BIN\POLY the following results may be obtained:


    fullpath = buildpath("TEST")

then
    fullpath == "c:\bin\poly\test"

evaluates to TRUE.

The buildpath function also expands directories referenced as ".." or ".". This
function may also be used to convert paths containing forward slashes or mixed
forward and backslashes to all backslashes. This is particularly useful when
comparing paths.

____________

Value returned:

The value returned by the buildpath function is the string containing the
explicit, fully expanded path.


ΓòÉΓòÉΓòÉ 14.19.4. chdir() ΓòÉΓòÉΓòÉ

chdir()   Primitive

Purpose: Set the default directory.

____________

Syntax:  int chdir(str path)

____________

Description: chdir() changes the current working directory to the directory
contained in the path argument.  The function will fail if path does not
specify an existing directory.

The path argument may contain a drive element.  When path contains a drive
element, that drive becomes the default drive.  When using this function to
change drives you must specify the drive letter followed by a colon as a
minimum.

When the path argument is a literal string rather than a variable, it must be
enclosed in double quotes.  Backslashes or forward- slashes may be used as path
separators. Keep in mind that backslashes must be quoted with a second
backslash in PEL source code.

____________

Value returned:

When chdir is successful a non-zero value is returned.  A returned value of
zero indicates failure.

____________

Compatibility:

chdir() differs from like-named C function supported by major compilers in that
the default drive may be changed with this function.  Return values also
differ.

____________

Example:

chdir("b:\\test")


ΓòÉΓòÉΓòÉ 14.19.5. close_pipes() ΓòÉΓòÉΓòÉ

close_pipes()   Primitive

Purpose:   Close the pipes opened by create_pipes()

____________

Syntax:   void   close_pipes([pipeid pipe])

____________

Description: Closes the specified pipeid.  If the pipeid is not specified, then
the last pipe that was opened will be closed.

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.19.6. create_pipes() ΓòÉΓòÉΓòÉ

create_pipes().   Primitive

Purpose: Opens I/O pipes to communicate with other programs

____________

Syntax:  pipeid create_pipes([long buffer_size])

____________

Description: Opens two pipes, one for input and one for output and returns a
"Handle" to the new pipes that may be passed to other primitives such as
process_pipes, system, pread, pwrite, etc...

If the buffer_size is specified it is used as the size of the OS's pipe buffer.
If it is not specified 1K bytes is assumed.

____________

Value returned:

Handle to the new pipes.


ΓòÉΓòÉΓòÉ 14.19.7. create_temp_name() ΓòÉΓòÉΓòÉ

create_temp_name()   Primitive

Purpose: Creates a string containing a unique filename.

____________

Syntax: str create_temp_name([int min_size, [str extension, [str prefix]]])

____________

Description: The create_temp_name() function creates a unique filename, using
the path named by the TMP or TEMP environment variable.  This function provides
the filename, including drive and path elements, in string form.  While this
function does create the file, it does nothing to ensure that the file will
automatically be deleted.

The optional min_size argument allows you to specify the anticipated file size
in advance.  Given this information, the function will ensure that the path
selected for the file has adequate storage space available for the file.  The
min_size argument represents the minimum file size in bytes.

The optional extension argument allows you to specify the extension the
temporary filename should have.  The default file extension is TMP.

The optional prefix argument allows you to specify the prefix used in creating
the temporary filename.  Only the first 3 characters of the prefix is used.  If
the prefix is not an empty string the temporary name will contain:

  pre_001.ext

  where pre is the prefix specified and 001 is used to make the
file
  name unique.

The filename provided by this function should be created before making
subsequent calls to this function.  If the file is not created, the same
filename could be selected again.

____________

Value returned: The value returned by the create_temp_name() function is the
newly created string containing the filename.  If all of the directories
designated for temporary files are full, the function will fail and return an
empty string.


ΓòÉΓòÉΓòÉ 14.19.8. disk_free() ΓòÉΓòÉΓòÉ

disk_free()   Primitive

Purpose: Reports storage space available on a drive.

____________

Syntax:  int disk_free([str drive or int drive])

____________

Description: If the drive argument is present, disk_free() reports the amount
of free disk space for the drive specified in that argument.  The drive
argument may be a string whose first character is the letter of the drive of
interest.  The rest of the string is ignored.  Alternately, drive may be a
drive number, where drive A: is 0, drive B: is 1 and so on.

If drive is not supplied, disk_free() reports the amount of free disk space for
the default drive.

____________

Value returned:

The number of bytes of free disk space is returned on successful completion.  A
value of zero is returned if the function has failed.

To distinguish between a disk-full condition and an invalid drive specification
(or other error) it is necessary to consult the errno variable. If this
variable is zero, the disk is full. Non-zero values for errno indicate that the
function failed.


ΓòÉΓòÉΓòÉ 14.19.9. dos_box() ΓòÉΓòÉΓòÉ

dos_box()   PEL

Purpose:  Execute system commands from within the editor.

____________

Syntax:   int function dos_box(cmd, flags, title)

____________

Arguments:

o cmd - command to execute
o flags - flags that are passed to the system command
o title - string title to use for the dos box

Description: The dos_box() command displays a dialog box that allows the user
to enter system commands.  You can use the scrap buffer to paste and copy text
to the command line.  The up and down arrow keys work like you would expect in
an OS/2 window, displaying the last commands eneterd. Click on OK or press
Enter to execute the command.  Click on Cancel to close the dialog.

Value returned: Return code from the system() command.


ΓòÉΓòÉΓòÉ 14.19.10. dos_drive() ΓòÉΓòÉΓòÉ

dos_drive()   Primitive

Purpose: Obtain or set the current drive.

____________

Syntax:  str dos_drive([str id or int id])

____________

Description: dos_drive() has two modes of operation. The mode selected depends
on whether the id argument has been supplied. If id is present, the drive it
specifies becomes the current default drive.  In this mode, id may be any
string whose first character is the letter of the drive which is to become the
default.  The rest of the string is ignored.  Alternately, id may be a drive
number, where drive A: is 0, drive B: is 1 and so on.

If id is not supplied, dos_drive() is treated as an inquiry as to which drive
is the current default.

____________

Value returned:

On success, dos_drive() returns a new string.  This string contains the letter
of the drive which is the current default followed by a colon.  This string
reflects the new default drive, if any has been requested.

On failure, an empty string is returned.


ΓòÉΓòÉΓòÉ 14.19.11. dos_verify_state() ΓòÉΓòÉΓòÉ

dos_verify_state()   Primitive

Purpose: Obtain or set the verify flag.

____________

Syntax:  int dos_verify_state([int state])

____________

Description: When the DOS verify flag is on, writes to disk are immediately
re-read to ensure that the correct data has been written.  The
dos_verify_state() function may be used to check and set the status of this
flag.

The state argument, if supplied, may be either zero or non-zero.  The value of
0 indicates that the verify flag is to be turned off, while any other value
indicates that it is to be turned on.

If the state argument is omitted, the function is treated as an inquiry only
and the verify flag is not modified.

____________

Value returned: dos_verify_state() returns the status of the verify flag in
effect at the time this function was called.  This function cannot fail.


ΓòÉΓòÉΓòÉ 14.19.12. dos_window() ΓòÉΓòÉΓòÉ

dos_window()   Primitive

Purpose: Run a command in a window.

____________

Syntax:  int dos_window([str command])

____________

Description: The dos_window() function is like the system() function in that it
allows you to execute a DOS command without leaving the editor. However, output
appears in the current window rather than printing the output on a cleared
screen.  There are some limitations on the use of this function, however, which
are discussed below.

The command to be executed is specified by the command argument.  If this
argument is omitted the command interpreter described by the COMspeC
environment variable is invoked.  By default this command interpreter is
COMMAND.COM.  In this case you must type EXIT_ to return to the editor.

Example:   dos_window("dir")  The output from this command may be redirected to
a file, however, the output will continue to appear on the screen.  In
addition, if the redirected output exceeds 16K characters, only the last 16K
are saved in the file.

Example:   dos_window(">out")  This example invokes the command interpreter and
redirects all output to a file named OUT.

The current window may be an icon or otherwise too small to display the output
from the command.  In this case the screen is cleared and the output is
displayed there unless it has been redirected.

Some cosmetic aspects of the output are determined by the cursor location
within the window when dos_window() is called.  If the cursor is in the upper
left corner of the window the screen will be cleared before output begins.
Otherwise output will appear at the cursor location overwriting any text
already visible there. The contents of the buffer, however, is not overwritten.
Some cautions must be observed in using this functions:  1) Do not run programs
such as MODE that reset the display mode. 2) Do not use this function if you
have any programs installed that boost the speed of output to the screen.  This
includes any of the SCREEN BOOST programs included in the PolyBoost package and
other programs that take over interrupts 10H or 29H.

____________

Value returned:

The value returned by the dos_window() function is the error code returned by
the command executed.

____________

See also:  system()


ΓòÉΓòÉΓòÉ 14.19.13. editor_path() ΓòÉΓòÉΓòÉ

editor_path()   PEL

Purpose: Tells where the editor Home Directory is.

____________

Syntax:  str editor_path()

____________

Description: The editor_path() function reports the directory in which the
editor has been installed.  This is generally referred to as the editor Home
Directory, which usually contains the editor executables, configuration file
and function library.

____________

Value returned:

The editor_path() function returns a string containing the path where the
editor environment variable points. If the variable has not been defined, an
empty string is returned.


ΓòÉΓòÉΓòÉ 14.19.14. fclose() ΓòÉΓòÉΓòÉ

fclose()   Primitive

Purpose: Close the file associated with a handle.

____________

Syntax:  int fclose(fileid handle)

____________

Description: fclose() closes the file indicated by the handle argument.  The
handle argument must be a file handle created with fopen().

____________

Value returned:

fclose() returns a non-zero (TRUE) value if successful.  Upon failure, zero or
FALSE is returned.

____________

Compatibility: Return values differ from those of the like-named C function
supported by major compilers.


ΓòÉΓòÉΓòÉ 14.19.15. fgetc() ΓòÉΓòÉΓòÉ

fgetc()   Primitive

Purpose: Gets a character from a file.

____________

Syntax:  int fgetc(fileid file)

____________

Description: The fgetc() function reads the next character from the file
described by the file argument.  This function allows reading the contents of a
file into a string or other variable rather than into a buffer.

____________

Value returned:

The value returned by fgetc() is an integer corresponding to the value of the
character read from the file.  When successful, this value will not be a
negative number.  If this function encounters the end of file or an error
occurs a -1 value is returned and the errno variable is set.  If errno is zero,
the end of file was encountered. When errno is other than zero an I/O error has
occurred.  This function will fail on files that have been opened in
Create/Truncate (Write Only) mode.


ΓòÉΓòÉΓòÉ 14.19.16. fgets() ΓòÉΓòÉΓòÉ

fgets()   Primitive

Purpose:  To get a string from a file handle.

____________

Syntax:   fgets( long fd )

____________

Arguments:

o fd - file handle to use

Description: This function is similar but not identical to its C counterpart.
It reads from the file handle's current offset until either it reaches a
newline character or it reaches the end of the file.  The newline character is
stripped out of the returned string.

____________

Value returned: The string read from the file handle, or if the end of the file
is reached, 0.  If the only character on the line was the newline character,
returns " ", a space.


ΓòÉΓòÉΓòÉ 14.19.17. filecopy() ΓòÉΓòÉΓòÉ

filecopy()   Primitive

Purpose: File copying utility.

____________

Syntax:  int filecopy(str old, str new)

____________

Description: The filecopy() function makes a duplicate of the file described by
the old argument under the name or path location indicated in the new argument.

The arguments taken by filecopy() may contain drive specifiers.  If an argument
contains no path element the current working directory is assumed.

If the file named in the new argument already exists, it is overwritten.  If
the file described by the old argument cannot be opened or read the new file is
not created or overwritten.  The new file is marked with the current date and
time.

When the new or old argument is expressed as a constant, it must be enclosed in
double quotes.  Backslashes or forward- slashes may be used as path separators.
Keep in mind that backslashes must be quoted with a second backslash in PEL
source code.

____________

Value returned:

Upon successful completion, filecopy() returns TRUE (non-zero).  On failure, it
returns FALSE (zero).


ΓòÉΓòÉΓòÉ 14.19.18. filemode() ΓòÉΓòÉΓòÉ

filemode()   Primitive

Purpose: Obtain or set the attributes of a file if it exists.

____________

Syntax:  int filemode([str name [, int mode]])

____________

Description: The filemode() function may be used to determine if a file exists
and, if it exists, may be used to check or set the DOS file attributes of that
file.  When the mode argument is present, filemode() modifies the permission
settings associated with the file indicated by the name argument.

The name argument is a filename and optional path element.  The path element
may include a drive specification.  If name contains no path element, the
default drive and directory are assumed.  If the name argument is not supplied,
this function obtains the file attributes of the file which was the subject of
last call to findfirst() or findnext().  If neither of these functions has been
called during the current editor session, it is treated as an error.

The new attribute settings are determined by which bits of the mode argument
are set. Interpretation of the mode bits is performed as follows:

Bit #   Attribute  Value to use
Bit0    mode=1  Read-only
Bit1    mode=2  Hidden
Bit2    mode=4  System
Bit5    mode=32  Archive

The above attributes may be combined by either supplying each of the desired
values separated by the OR operator ( | ), or by adding the appropriate values
together. Only the least significant eight bits of mode are considered.

If the mode argument is absent, this function is treated as an inquiry only.
File attributes are not modified. filemode() may be used in this manner to
determine if a file is present on disk.

____________

Value returned:

Upon successful completion, filemode() returns the attributes of the file at
the time the function was called.  If the file represented by the name argument
does not exist or some other error occurs a value of -1 will be returned.

Interpretation of the value returned is the same as the mode argument described
above. All bits not in the least significant byte should be ignored since these
are used to distinguish between a file attribute mask of 0 and a failure.

____________

Compatibility: This function serves a similar purpose to the chmod() or
access() functions supported by major C compilers.  However, it differs from
the PEL filemode() function in arguments and return value.


ΓòÉΓòÉΓòÉ 14.19.19. filemove() ΓòÉΓòÉΓòÉ

filemove()   Primitive

Purpose: File moving utility

____________

Syntax:  int filemove(str old, str new)

____________

Description: filemove() copies the file described by the old argument to the
name or path location indicated in the new argument.  The original file is then
deleted.

The arguments taken by filemove() may contain drive specifiers.  If an argument
contains no path element the current working directory is assumed.  The
filename must be explicitly named in both the old and new arguments.

If the file named in the new argument already exists, it is not overwritten.
If the file described by the old argument cannot be opened, read or deleted the
new file is not created or overwritten.  The new file is marked with the
current time and date.

When the new or old argument is expressed as a constant, it must be enclosed in
double quotes.  Backslashes, forward- slashes or doubled backslashes may be
used as path separators.

____________

Value returned:

Upon successful completion, filemove() returns a non-zero (TRUE) value.  On
failure, it returns zero or FALSE.  Consult errno to determine the source of
the error.


ΓòÉΓòÉΓòÉ 14.19.20. filesize() ΓòÉΓòÉΓòÉ

filesize()   Primitive

Purpose: Determine the size of a file.

____________

Syntax:  int filesize([str name])

____________

Description: filesize() is used to determine the amount of storage occupied by
the file indicated in the name argument.

The name argument is a filename and optional path element.  The path element
may include a drive specification.  If name contains no path element, the
default drive and directory are assumed.  If the name argument is not supplied,
this function obtains the file size of the file which was the subject of last
call to findfirst() or findnext().  If neither of these functions has been
called during the current editor session, it is treated as an error.

____________

Value returned:

When successfully completed, the value returned by filesize() is the number of
bytes occupied by the file.  If the file does not exist or another error
occurs, the value returned is -1.

____________

Compatibility: This function is common to the editor and PEL.


ΓòÉΓòÉΓòÉ 14.19.21. filetime() ΓòÉΓòÉΓòÉ

filetime()   Primitive

Purpose: Obtain or set the timestamp associated with a file.

____________

Syntax:  int filetime([str file [, int timestamp]])

____________

Description: When the timestamp argument is supplied, filetime() sets the time
and date of the file described in the file argument to the value of timestamp.

The file argument is a string containing a filename.  This filename may not
contain wildcard characters.  Optionally, file may also contain a path element
including drive specifier.  If file does not contain a path element, the
default drive and directory are assumed.  If the file argument is not supplied,
this function obtains the timestamp of the file which was the subject of last
call to findfirst() or findnext(). If neither of these functions has been
called during the current editor session, it is treated as an error.

The value supplied in the timestamp argument represents the time and date of
the file in seconds since 00:00:00 January 1, 1970.  If timestamp is 0, the
file will be set to the current system date and time. When timestamp is
omitted, the function is treated as an inquiry only.  The timestamp on the file
is not modified.

____________

Value returned:

Upon successful completion, filetime() returns the date and time of the file in
effect when the function was called.

If an error occurs, a value of zero is returned.

____________

Compatibility:

This function is common to the editor and PEL.


ΓòÉΓòÉΓòÉ 14.19.22. filter() ΓòÉΓòÉΓòÉ

filter()   PEL

Purpose: Processes a portion of a buffer through a command.

____________

Syntax:  int filter(str command)

____________

Description: The filter() function runs a portion of the current buffer through
the command specified by the command argument.  The filter specified by the
command argument must be a program that takes its input from the standard input
device and sends the results to the standard output device.

If a marked block of text has been defined, the text in that block is processed
through the indicated command.  If no marked block exists, the entire buffer is
processed. After the text has been processed, the resulting text is read into
the buffer as a replacement for the marked block or buffer contents.

____________

Value returned:

The value returned by the filter() function is the exit code returned by the
filter subprocess.  This usually means a return value of 0 signifies success.


ΓòÉΓòÉΓòÉ 14.19.23. findfirst() ΓòÉΓòÉΓòÉ

findfirst()   Primitive

Purpose: Begin a directory search.

____________

Syntax:  str findfirst(str pattern [, int attr])

____________

Description: findfirst() searches the directory for the first file, if any,
matching the pattern argument.  The match may be further qualified by the file
attribute described by the attr argument.

The pattern argument is a filename which may contain standard DOS wildcard
characters, * and ?, as described in the "Filename Matching" section of
"General Operation" chapter of the User's Manual. It may also have a path
element including drive specifier.  If pattern contains no path element, the
default drive and directory are assumed.  Note!  Although a path may be
specified as part of the pattern argument, this function returns only
filenames, not paths.

The search may be further limited or expanded by supplying the attr argument.
This argument describes the file attributes that the directory entry must
match.  If this argument is not supplied, normal, read-only and files with the
archive bit set will match.

The values allowed for attr are those that may be represented by a single byte.
A number of descriptive identifiers have been defined in the standard library
files for your use.  These identifiers and their numeric values are given
below:  Identifier  Value _READ_ONLY  0x01 _HIDDEN    0x02 _SYSTEM    0x04
_VOL_ID    0x08 _SUBDIR    0x10 _ARCHIVE   0x20 _NORMAL    0x40

Any combination of the above values may be specified as the attr argument.  For
instance, either of the examples below matches with files that have the Archive
or Read-Only bits set: findfirst("*.*",_ARCHIVE + _READ_ONLY)
findfirst("*.*",0x21)

If you omit any of the library function files from a customized configuration
of the editor, the identifiers list above may become unavailable.  If so, you
will have to define similar variables yourself or use the numeric equivalent.

____________

Value returned:

Returns a string containing the filename found.  The string returned does not
contain any path element.

If no matching file is found or some other error occurs, an empty string is
returned. If an empty string is returned and errno is zero, no matching file
was found. Otherwise, some other error occurred.

____________

Compatibility:

This function is somewhat similar to the findfirst() or _dos_findfirst function
supported by some C compilers.  The value corresponding to the _NORMAL label
has been changed to allow searches that do not implicitly include these files.


ΓòÉΓòÉΓòÉ 14.19.24. findnext() ΓòÉΓòÉΓòÉ

findnext()   Primitive

Purpose: Continue a directory search.

____________

Syntax:  str findnext()

____________

Description: Subsequent to a call to findfirst(), the findnext() function is
used to find the next file matching the pattern argument used in findfirst().

____________

Value returned:

Returns a string containing the filename found.  The string returned does not
contain any path element.

If no further matching file is found or some other error occurs, an empty
string is returned.  If an empty string is returned and errno is zero, no
matching file was found.  Otherwise, some other error occurred.

____________

Compatibility:

This function is somewhat similar to the findnext() or _dos_findnext function
supported by some C compilers.


ΓòÉΓòÉΓòÉ 14.19.25. fopen() ΓòÉΓòÉΓòÉ

fopen()   Primitive

Purpose: Open a file for processing.

____________

Syntax:  fileid fopen(str file, int mode)

____________

Description: The fopen() function opens the file indicated by the file argument
in the manner indicated by the mode argument.

The file argument may contain a path element, including drive specifier, as
well as the required filename.

One of the permissions indicated below may be specified by mode:

Permission mode Description
0         Read only permission.
1         Create/Truncate (Write Only).
2         Read and Write permission.  (When used with fseek() allows
          appending.)

____________

Value returned:

fopen() returns the file handle of the file it has opened, upon successful
completion. Zero may be a valid file handle.  On error, this function returns a
value of -1. Further information may be available by examining the errno
variable.

____________

Compatibility:

Similar to the fopen() function supported by major C compilers.  Return values
and modes available are somewhat different.


ΓòÉΓòÉΓòÉ 14.19.26. fprintf() ΓòÉΓòÉΓòÉ

fprintf()   Primitive

Purpose: Writes a formatted string to a device.

____________

Syntax:  void fprintf(fileid handle, str fmt [, any args,...])

____________

Description: The fprintf() function formats a string, as indicated by the fmt
and args arguments and writes it on the device indicated by the handle
argument.  The handle argument must be a file id returned by the fopen()
function.  The fmt string argument may contain both text to be printed
literally and format control characters.  Format control characters specify how
the args arguments are to be formatted and included in the output string.

Format control characters are preceded by the percent ( % ) symbol.  The
recognized format control characters and their meanings are given below:

Format char.   Meaning
c              An ASCII character.
d or ld        An integer (decimal notation).
o              An unsigned integer (octal notation).
s              A string
x              An unsigned integer (hex. notation).
X              An unsigned integer (hex. , upper case letters).

Since the % indicates that a format control character follows, %% must be used
to represent a single percent symbol in the fmt string.

There may be an intervening number, dash or a dot (followed by a number)
between the % symbol and its format control character. The number indicates the
reserved width of the field.  The field is padded until it is this width.  If
the number contains a leading zero, the field is padded with zeros.  Otherwise
the field is padded with spaces.

The intervening dash ( - ) indicates that the expression is to be left
justified within the field.  In the absence of the dash, the field will be
right justified.

The dot ( . ) is used to specify the maximum string width.  The number
following the dot represents the maximum length of the string expression to be
included.  If the expression is longer than the specified maximum, the
remainder is truncated.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.19.27. fputc() ΓòÉΓòÉΓòÉ

fputc()   Primitive

Purpose: Puts a character in a file.

____________

Syntax:  void fputc(int ch, fileid file)

____________

Description: The fputc() function writes a character to the file described by
the file argument. The integer argument, ch, contains the value of the
character.  This function uses fprintf() to achieve this result.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.19.28. fread() ΓòÉΓòÉΓòÉ

fread()   Primitive

Purpose: Read a portion of a file into the active buffer.

____________

Syntax:  int fread(fileid handle, markid mark, int len)

____________

Description: The fread() function reads the number of characters indicated by
the len argument from the file specified by handle.  This data is then inserted
into the active buffer at the location indicated by the mark argument.

The file handle supplied in the argument handle must have been previously
created by the fopen function.

The mark argument is the number of a previously defined editor bookmark in the
active buffer.  Bookmark 0 is always defined as the current cursor position in
that buffer.

The len number of bytes to read is limited to 8100 bytes per read.

____________

Value returned:

Upon success, fread() returns the number of bytes read.  If the handle or mark
argument is invalid or if the file has been opened in a mode that does not
permit reading this function will return -1.

When the value returned is less than len, the end of the file has been reached
or a media failure has occurred.  If a media failure is suspected, errno may
then be consulted for additional information.

____________

Compatibility:

This function differs from the ANSI C fread function in its return values and
the destination of the data read.


ΓòÉΓòÉΓòÉ 14.19.29. fseek() ΓòÉΓòÉΓòÉ

fseek()   Primitive

Purpose: Move the file pointer.

____________

Syntax:  int fseek(fileid handle, int offset, int flag)

____________

Description: The fseek() function sets the pointer associated with a file to a
new location. The file pointer to be moved is the pointer associated with the
handle argument.  It is moved to the position indicated by the flag argument
plus offset bytes.  You may determine the current position using the ftell()
function.

The permissible values for flag and their meaning are as follows:

Value     Meaning
0         The beginning of the file.
1         The file pointer's current position.
2         The end of the file.

____________

Value returned:

On successful completion, fseek returns the file pointer offset.  When seeking
to the beginning of a file the return value will be zero.  If an error occurs,
a value of -1 is returned.

____________

Compatibility:

This function is similar to the like-named function supported by major C
compilers except as to return values.

____________

See also:  ftell()


ΓòÉΓòÉΓòÉ 14.19.30. ftell() ΓòÉΓòÉΓòÉ

ftell()   Primitive

Purpose: Reports current position of file pointer.

____________

Syntax:  int ftell(fileid handle)

____________

Description: ftell() obtains the current position of the file pointer
associated with the file indicated by the handle argument.

____________

Value returned:

ftell() returns the file pointer position in number of bytes from the beginning
of the file, when successful.  When the file pointer is at the beginning of the
file this value will be zero.

On error, ftell() returns -1.  To differentiate an error from the beginning of
the file, consult the errno variable. If the file pointer is pointing to the
beginning of the file, ftell() will return zero and errno will also be zero.
If errno is a non-zero value, an error has occurred.

____________

Compatibility:

This function is similar to the ftell function supported by major C compilers
except as to the value returned on error.


ΓòÉΓòÉΓòÉ 14.19.31. fwrite() ΓòÉΓòÉΓòÉ

fwrite()   Primitive

Purpose: Write a block of text to a file.

____________

Syntax:  int fwrite(fileid handle, markid mark, int len)

____________

Description: The fwrite() function writes the number of characters indicated by
the len argument to the file specified by handle from the active buffer.  The
beginning of the data to be written is indicated by the mark argument.  The
write operation begins at the position indicated by the file pointer associated
with handle.

The file handle supplied in the argument handle must have been previously
created by the fopen() function.

The mark argument is the number of a previously defined editor bookmark in the
active buffer.  Bookmark 0 is always defined as the current cursor position in
that buffer. If you wish to truncate a file at its current position, supply a
value of 0 as the len argument to this function.  When writing a highlighted
block of text, write_marked_block() is the appropriate function to use.  When
writing all text between two bookmarks, the distance_between_marks() function
may be used to provide the len value.

____________

Value returned:

Upon success, fwrite() returns the number of bytes actually written.  If the
handle or mark argument is invalid or if the file has been opened in a mode
that does not permit writing this function will return - 1.

Anytime the value returned is less than len, an error has occurred.  errno may
then be consulted to determine the source of the error.

____________

Compatibility:

This function differs from the fwrite function supported by major C compilers
in its return values and the origin of the data written.

____________

See also:  write_marked_block()


ΓòÉΓòÉΓòÉ 14.19.32. getcwd() ΓòÉΓòÉΓòÉ

getcwd()   Primitive

Purpose: Obtain the current working directory of a drive.

____________

Syntax:  str getcwd([str drive or int drive])

____________

Description: If the drive argument is present, getcwd() reports the current
working directory, including full path name, for the drive specified in that
argument.  The drive argument may be a string whose first character is the
letter of the drive of interest.  The rest of the string is ignored.
Alternately, drive may be a drive number, where drive A: is 0, drive B: is 1
and so on.

If drive is not supplied, getcwd() reports the current working directory for
the default drive.

____________

Value returned:

On success, getcwd() returns a new string. This string contains the full path
name of the current working directory, including drive specifier.  The string
always ends with a backslash and may be up to 129 characters long.

On failure, an empty string is returned.

____________

Compatibility:

getcwd() differs from the getcwd function supported by major C compilers.  The
getcwd C function only returns the current working directory of the default
drive, whereas getcwd() may be used to obtain the current working directory of
any valid drive.

The arguments required by these two functions are also different.


ΓòÉΓòÉΓòÉ 14.19.33. idle() ΓòÉΓòÉΓòÉ

idle()   Primitive

Purpose: Allows processing of the message queue

____________

Syntax: void idle()

____________

Description: The idle() function allows processing of the PM or Windows message
queue.  Currently both PM and Windows implement a cooperative multi- tasking
when it comes to handling thier respective message queues. The idle() function
allows processing this message queue while executing PEL code.  Use this
function with care as most of the PEL code is not reentrant and calling the
idle() function may cause PEL code to be executed.  For instance, if in the
middle of a long PEL process call idle() but do not allow the function you are
currently executing to be called again.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.19.34. mkdir() ΓòÉΓòÉΓòÉ

mkdir()   Primitive

Purpose: Create a new directory.

____________

Syntax: int mkdir(str dir)

____________

Description: mkdir() makes a new directory according to the path and directory
name given in the dir argument.

____________

Value returned: If successful, mkdir() returns a non-zero value. If an error
occurs, a value of zero is returned. When a zero is returned, the errno will
provide further information about the error.  If a directory or file by the
name found in dir already exists, or if some other error has occurred, errno
will be non-zero.

____________ Compatibility: This function is similar to the like-named function
supported by major C compilers except as to return values.


ΓòÉΓòÉΓòÉ 14.19.35. path_ext() ΓòÉΓòÉΓòÉ

path_ext()   Primitive

Purpose: Extract the filename extension from a string.

____________

Syntax: str path_ext(str s)

____________

Description: The path_ext() function creates a new string containing the
filename extension found in the s argument.  The new string begins with the dot
found in the argument.  The string following the dot will be a maximum of three
characters.

____________

Value returned: The value returned by the path_ext() argument is the newly
created string.  If the string does not contain a dot, or period, the string
returned will be empty.  If the argument string is undefined, an empty string
will be returned.


ΓòÉΓòÉΓòÉ 14.19.36. path_fname() ΓòÉΓòÉΓòÉ

path_fname()   Primitive

Purpose: Extract a filename from a string.

____________

Syntax: str path_fname(str s)

____________

Description: The path_fname() function creates a string from the s argument.
The s argument contains a filename and often a path element.  This function
locates the filename within the string and copies it, less any extension, into
the new string.

____________

Value returned: The value returned by the path_fname() function is the newly
created string.  If the argument provided does not contain a filename and does
not end with a path delimiter ( / or \ ), the last element of the path is
returned.  If the argument is not a defined string, an empty string is
returned.


ΓòÉΓòÉΓòÉ 14.19.37. path_path() ΓòÉΓòÉΓòÉ

path_path()   PEL

Purpose:  To return the path portion of a fully qualified path and filename.

____________

Syntax:   path_path( str pathfname )

____________

Arguments:

o pathfname  -  a fully qualified path and file name

Description: This function is a handy utility that will take a fully qualified
file name, such as buffer_filename, and return the path portion of the string,
including the trailing backslash.

____________

Value returned:  The path including the trailing backslash


ΓòÉΓòÉΓòÉ 14.19.38. pgetc() ΓòÉΓòÉΓòÉ

pgetc()   Primitive

Purpose:  Read a character from a read pipe. Does not return until a character
is available.

Syntax:   short pgetc([pipeid pipe])

____________

Description: Reads a character from the pipeid.  If the pipeid is not supplied
then the character is read from the last pipe opened.

____________

Value returned: The character read from the pipe.


ΓòÉΓòÉΓòÉ 14.19.39. pgets() ΓòÉΓòÉΓòÉ

pgets()   Primitive

Purpose:  Read a string from an input pipe. Does not return until data is
available.

Syntax:   string pgets([long len, [pipeid pipe]])

____________

Arguments:

o len  - Number of bytes to read.
o pipe -  PipeID of the pipe to read, Defaults to the last pipe opened.

Description: Reads a string of len bytes from the pipeid.  If the pipeid is not
supplied then the string is read from the last pipe opened.

____________

Value returned: The string read from the pipe.


ΓòÉΓòÉΓòÉ 14.19.40. pop_dir() ΓòÉΓòÉΓòÉ

pop_dir()   PEL

Purpose: Makes previously stored directory current.

____________

Syntax: void pop_dir()

____________

Description: The pop_dir() function restores as the current working directory a
path that was previously saved on a stack.  The push_dir() function is used to
store the current working directory on this stack.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.19.41. pputc() ΓòÉΓòÉΓòÉ

pputc()   Primitive

Purpose:  Write a character into an output pipe.

Syntax:   void pputc(short ch, [pipeid pipe])

____________

Arguments:

o ch  - The character to write.
o pipe -  PipeID of the pipe to write to, Defaults to the last pipe opened.

Description: Writes a character to the pipeid.  If the pipeid is not supplied
then the character is written to the last pipe opened.

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.19.42. pputs() ΓòÉΓòÉΓòÉ

pputs()   Primitive

Purpose:  Write a string into an output pipe.

Syntax:   void pputs(string data, [pipeid pipe])

____________

Arguments:

o data -  The string to write.
o pipe -  PipeID of the pipe to write to, Defaults to the last pipe opened.

Description: Writes a string to the pipeid.  If the pipeid is not supplied then
the string is written to the last pipe opened.

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.19.43. pread() ΓòÉΓòÉΓòÉ

pread()   Primitive

Purpose:  Read a string from an input pipe into the active buffer.

Syntax:   long pread(markid mark,long len, [pipeid pipe])

____________

Arguments:

o mark - Position in the current buffer to insert the string at.
o len - Number of bytes to read.
o pipe - PipeID of the pipe to read, Defaults to the last pipe opened.

Description: Reads a string of len bytes from the pipeid.  If the pipeid is not
supplied then the string is read from the last pipe opened.

____________

Value returned: The number of bytes actually read or -1 for error.


ΓòÉΓòÉΓòÉ 14.19.44. process_pipes() ΓòÉΓòÉΓòÉ

process_pipes()   Primitive

Purpose:  Process strings from an input pipe. Issues PIPE_DATA_EVENTs when data
is available.

Syntax:   long process_pipes([pipeid,[bool bufferLines, [bool insert]]])

____________

Description: Starts a second thread which reads a string from the input pipe
and then issues a PIPE_DATA event.  Since the processing is performed in a
second thread the primitive will return immediatly. The second thread continues
execution until the pipe is closed.  If bufferLines is set, then the PIPE_DATA
will be returned one line at a time regardless of how the child process sends
it.  If insert if set, EVENT.PIPE_DATA events will not be generated, instead
the piped data will be inserted into the current_buffer. This method is used by
the dos_window primitive.  If the pipeid is not specified,  then the last pipe
opened will be processed.

____________

Value returned: The Thread ID of the second thread or 0 if an Error occured.


ΓòÉΓòÉΓòÉ 14.19.45. push_dir() ΓòÉΓòÉΓòÉ

push_dir()   PEL

Purpose: Saves the current directory and logs to new one.

____________

Syntax: void push_dir(str new_cwd)

____________

Description: The push_dir() function records the current working directory on a
"stack" and makes the directory named in the new_cwd argument current.  The
pop_dir() function is used to restore the directory most recently saved on the
stack.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.19.46. pwd() ΓòÉΓòÉΓòÉ

pwd()

Purpose: Displays the current working directory

____________

Syntax: pwd()

____________

Arguments: None.

____________

Description:  The pwd() function displays the current working directory in a
message box or on your status bar.

____________

Value returned: The current working directory.


ΓòÉΓòÉΓòÉ 14.19.47. pwrite() ΓòÉΓòÉΓòÉ

pwrite()   Primitive

Purpose:  Write a block of text to an output pipe.

Syntax:   long pwrite(markid mark,long len, [pipeid pipe])

____________

Arguments:

o mark - The beginning of the data to be written from the current buffer.
o len - Number of bytes to write.
o pipe - PipeID of the pipe to write, Defaults to the last pipe opened.

Description: Writes a string to the pipeid.  If the pipeid is not supplied then
the string is written to the last pipe opened.

____________

Value returned: The number of bytes actually written or -1 for error.


ΓòÉΓòÉΓòÉ 14.19.48. query_pid() ΓòÉΓòÉΓòÉ

query_pid   Primitive

Purpose:  Query the process id of a pipe.

____________

Syntax:   long query_pid([long pipeid])

____________

Arguments:

o pipeid -id of the pipe to query

Description: The query_pid() function returns the process id of the specified
pipe.  If no pipe id is supplied, the editor uses the default pipe id.

____________

Value returned: Process id of the specified pipe.


ΓòÉΓòÉΓòÉ 14.19.49. rename() ΓòÉΓòÉΓòÉ

rename()   Primitive

Purpose: Change the name of a file or series of files.

____________

Syntax: int rename(str old, str new)

____________

Description: The rename() function changes the names of files matching the file
specification in the old argument to match the pattern indicated by new.

The old and new arguments may not contain wildcard characters.  If the new file
specification contains a drive specifier, it must match that given in old.

____________

Value returned: When successful, rename() returns a non-zero value. If an error
occurs, a zero value is returned.

____________ Compatibility: rename() differs from the ANSI C function of the
same name in that return values are different.


ΓòÉΓòÉΓòÉ 14.19.50. rmdir() ΓòÉΓòÉΓòÉ

rmdir()   Primitive

Purpose: Delete a file directory.

____________

Syntax: int rmdir(str dir)

____________

Description: The rmdir() function removes the directory indicated by the dir
argument.

The dir argument may contain a path element, including a drive specifier.  If
no path element is supplied, the current working directory is assumed to be the
parent directory of the directory to be deleted.

To succeed, the directory indicated by dir must not contain any files and must
not be the current working directory.  Attempts to delete the root directory
will also fail.

____________

Value returned: If the directory is successfully removed, the rmdir() returns a
non-zero value.  If it fails, a zero value is returned.  Consult the errno to
determine the nature of the failure.

____________ Compatibility: This function is similar to the like-named function
supported by major C compilers, except as to return codes.


ΓòÉΓòÉΓòÉ 14.19.51. spawn() ΓòÉΓòÉΓòÉ

spawn()   Primitive

Purpose: Starts a detached process

____________

Syntax: long  spawn(string cmd [, string params])

____________

Description: The spawn() function starts a detached session.  The parent
process is not able to query any information about the new session.  This
function is useful if you want to use the editor to launch other applications
and are not concerned with their status.  Use the system() function if you need
more detailed information on a process once it has started.  This function
cannot be used to run operating system internal commands (i.e. dir).  The cmd
argument contains the name of the program to execute. The cmd argument must
contain a valid executable program.  The optional params argument contains any
command line arguments to pass to the program.

____________

Value returned: This function returns the value returned from the operating
system's attempt to execute the program.


ΓòÉΓòÉΓòÉ 14.19.52. system() ΓòÉΓòÉΓòÉ

system()   Primitive

Purpose: Allows command execution without exiting to OS2

____________

Syntax: long system([[[[[str command], any stdin], any stdout], any stderr],
short flags]) shell_parse]])

____________

Arguments:

o cmd - Command to be executed.

o inArg - The file to use for stdin, either a String that contains the
  filename, the FileId of an opened file to use, or the PipeId of a pipe
  created with create_pipes.  Any other type will cause stdin to NOT be
  re-directed.

o outArg - The file to use for stdout, either a String that contains the
  filename, the FileId of an opened file to use, or the PipeId of a pipe
  created with create_pipes.  Any other type will cause stdout to NOT be
  re-directed.

o errArg - The file to use for stderr, either a String that contains the
  filename. the FileId of an opened file to use, or the PipeId of a pipe
  created with create_pipes.  Any other type will cause stderr to NOT be
  re-directed.  If OutArg is specified and errArg is not, then stderr will also
  be re-directed to the stdout file.

o flags  - Bitmapped flags used to control how the command is executed:

    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
    ΓöéFlag           ΓöéHex value ΓöéDescription                   Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéSESSION        Γöé0x0001    ΓöéStart command in separate     Γöé
    Γöé               Γöé          Γöésession.                      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéSHELL          Γöé0x0002    ΓöéStart command with command    Γöé
    Γöé               Γöé          Γöéshell (CMD.EXE or COMMAND,COM)Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéASYNC          Γöé0x0004    ΓöéRun command asyncronously.    Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéDETACHED       Γöé0x0008    ΓöéDo not run command as a child Γöé
    Γöé               Γöé          Γöéprocess.                      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéNOEXPOSE       Γöé0x0010    ΓöéDo not allow exposes while    Γöé
    Γöé               Γöé          Γöécommand executes.             Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéNOSESSION      Γöé0x0020    ΓöéForce command to start in sameΓöé
    Γöé               Γöé          Γöésession.                      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéMAXIMIZE       Γöé0x0040    ΓöéStart session maximized.      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéMINIMIZE       Γöé0x0080    ΓöéStart session minimized.      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéQUIET          Γöé0x0100    ΓöéStart CMD.EXE with /Quiet     Γöé
    Γöé               Γöé          Γöéswitch.                       Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    ΓöéDOSSHELL       Γöé0x0200    ΓöéStart a DOS session.          Γöé
    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

  All commands default to synchronous execution. To perform an asynchronous
  command, precede the command name with the '@' sign, i.e. system( "@test.exe"
  ), runs 'test.exe' as an asynchronous child process. Also, if the flags
  parameter is not sepecified, the default is to run the command in a seperate
  session (if no files are re-directed).

  The flags may also be specified as leading characters in the cmd string, the
  values are as follows:

    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
    ΓöéFlag ΓöéDescription                             Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'@'  ΓöéRun command asyncronously.              Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'&'  ΓöéDo not run command as a child process.  Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'*'  ΓöéStart command with command shell        Γöé
    Γöé     Γöé(CMD.EXE or COMMAND,COM)                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'+'  ΓöéStart command in separate session.      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'?'  ΓöéForce command to start in same session  Γöé
    Γöé     Γöéas editor.                              Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'='  Γöé Do not allow exposes while command     Γöé
    Γöé     Γöéexecutes.                               Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'^'  ΓöéStart session maximized.                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'|'  ΓöéStart session minimized.                Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöé'%'  ΓöéStart a DOS session.                    Γöé
    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

o dos_settings - Table of DOS settings where the index is the setting name and
  the value is the value.  The available settings are the same as are shown in
  the DOS Settings dialog from the Settings notebook of a DOS Program Object.
  Examples:

    ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
    ΓöéSetting        ΓöéValue     Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöés["DOS_FILES"] Γöé10        Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöés["DOS_HIGH"]  Γöé"ON"      Γöé
    Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
    Γöés["DOS_UMB"]   Γöé0         Γöé
    ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Description: The system() allows executing an external OS/2, PM, or DOS
program.  The following arguments list the various options when executing the
system command.

____________

Value returned: Error code if command failed to execute, or return code of
command if command executed synchronously, else Process ID if command executed
asynchronously.

____________

See also:   SYS_ (system flags),dos_window()


ΓòÉΓòÉΓòÉ 14.19.53. system_key() ΓòÉΓòÉΓòÉ

system_key()   PEL

Purpose: Prompts user for operating system command.

____________

Syntax: void system_key()

____________

Description: The system_key() function prompts the user for a command and sends
it to the operating system for execution.  If the command fails, a warning
giving the error code is displayed in the dialog box. This function is intended
for processing single commands without "shelling out".  If it is necessary to
execute a series of commands, the system() function may be preferable.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.19.54. unlink() ΓòÉΓòÉΓòÉ

unlink()   Primitive

Purpose: Delete a file.

____________

Syntax: int unlink(str path)

____________

Description: unlink() removes the file indicated by path.  The path argument
must contain an explicit filename; no wildcard characters are allowed.  It may
also contain a path element, including drive specifier. If path contains no
path element, the current drive and directory are assumed.

When the path argument is expressed as a constant, it must be enclosed in
double quotes.  Backslashes, forward-slashes or doubled backslashes may be used
as path separators.

____________

Value returned: If the file indicated by path does not exist, or if permission
to delete the file is not obtained, a value of zero is returned.  Non-zero
values indicate the function was successfully completed.

____________ Compatibility: This function is identical to the ANSI C remove()
and the UNIX_ unlink() except as to return values.


ΓòÉΓòÉΓòÉ 14.19.55. unlock_edit_files() ΓòÉΓòÉΓòÉ

unlock_edit_files()   PEL

Purpose:  Unlocks all files that have been locked.

____________

Syntax:   void unlock_edit_files()

____________

Arguments: none.

Description: The unlock_edit_files() function unlocks all files which have been
locked by deleting the associated semaphore file.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.19.56. unlock_file() ΓòÉΓòÉΓòÉ

unlock_file()   PEL

Purpose:  Unlocks a filesthat has been locked.

____________

Syntax:   void unlock_file(str fname)

____________

Arguments:

o fname - name of file to unlock

Description: The unlock_file() function unlock fname by deleting the associated
semaphore file.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.20. Text Editing ΓòÉΓòÉΓòÉ

The functions in the Text Editing category allow you to modify the current
buffer in various ways.  These functions cover virtually all aspects of the
text editing process, from inserting the typed character to undoing or even
redoing major edits.

Undo and Redo

The undo and redo features deserve special mention.  The allows the user to
reverse the effects of one or a series of edit operations.  This has become a
popular and valued feature in a programmer's editor.

The PREDITOR/2 undo function can undo almost any operation affecting the
contents of a buffer -- except an undo operation itself.

The redo() function allows undoing the effects of an undo().  This not only
enables the user to restore edits that have inadvertently been undone, it
allows the user to alternate between two or more conditions of the buffer to
reflect on which is most desirable.  The undo_index() function allows you to
undo or redo even large numbers of edits in a single command.

PREDITOR/2 stores each operation on a buffer on an "undo/redo stack" and
assigned a sequential .  Each buffer has its own undo stack and sequence of
operation numbers.  For each call to the undo() function, PREDITOR/2 reverses
the most recent operation on the stack and decrements the current operation
number for that buffer.

An operation that has been undone is not lost, however, and is performed again
if redo() is called before further editing.  Whenever editing recommences, the
contents of the stack beyond the current operation are lost.

The current operation number may be obtained and recorded for later use by
calling the undo_index() function.  This number serves as a snapshot of the
current state of edits to the buffer.  The operation number obtained from
undo_index() may be supplied to the undo() function, which will undo all
operations subsequent to the one named.

It should be noted that, unlike many programmer's editors, the Sage
Professional Editor places no arbitrary limit on the number of operations that
may be undone. The number of edits that may be undone or redone is limited only
by available disk space.  Usually the number of edits between buffer saves will
be only a small fraction of the number possible.

append_to_scrap()
          Add text to the current contents of the scrap buffer.
backspace()
          Deletes the character preceding the cursor.
copy_to_scrap()
          Copy a portion of current buffer to scrap buffer.
copy_to_scrap_key()
          Copy or append portion of buffer to scrap.
cut()
          Copy text to the scrap buffer and then delete it.
delete_chars()
          Delete text from the current edit buffer.
delete_prev_word()
          To delete the word previous to the current cursor location.
delete_to_eol()
          Delete from the cursor position to the end of the line.
delete_to_scrap()
          Copy text to the scrap buffer and then delete it.
delete_word()
          Delete word or words following cursor.
indent_columns()
          Indent lines by adding whitespace to the left of text.
insert_key()
          Insert the character associated with a key into buffer.
insert_newline()
          Insert end-of-line marker and move cursor to next line.
insert_scrap()
          Insert contents of scrap buffer at cursor position.
open_line()
          Inserts a new line following the current line.
redo()
          Undoes the effects of a previous undo().
redo_index()
          Queries the value of the redo index.
undo()
          Reverses the effects of a previous edit operation.
undo_index()
          Reports current operation number of undo/redo stack.


ΓòÉΓòÉΓòÉ 14.20.1. append_to_scrap() ΓòÉΓòÉΓòÉ

append_to_scrap()   Primitive

Purpose: Add text to the current contents of the scrap buffer.

____________

Syntax:  int append_to_scrap()

____________

Description: If a block or region of text has been selected, the
append_to_scrap() function will copy the text in that block into the scrap
buffer.  If no block of text has been defined, the character at the cursor is
appended to the scrap buffer.

In any case, the text appended to the scrap buffer is not deleted from its
original location in the edit buffer.  Any previous contents of the scrap
buffer are preserved.

This function allows you to accumulate text in the scrap buffer which may later
be inserted elsewhere in the buffer with the insert_scrap() function.

____________

Value returned:

When successful, the append_to_scrap() function returns a non-zero value
(TRUE). If for any reason the function can not be completed, a zero (FALSE)
value will be returned.


ΓòÉΓòÉΓòÉ 14.20.2. backspace() ΓòÉΓòÉΓòÉ

backspace()   Primitive

Purpose: Deletes the character preceding the cursor.

____________

Syntax:  int backspace()

____________

Description: The effect of the backspace() function is dependent upon the value
on the buffer_flags variable.  If insert mode is in effect, this function
deletes the character preceding the current cursor position.  The contents of
the line to the right of the deleted character and the cursor are shifted to
the left.

If the buffer_flags variable specifies overtype mode, the backspace function
replaces the character preceding the current cursor position with a single
space.  The contents of the line to the right of the cursor does not move
unless the character deleted is a tab.  However, the cursor does shift to the
left.

When in insert mode, backspace() deletes the end-of-line marker on the
preceding line when the cursor is at the beginning of the line.  This has the
effect of appending the current line onto the preceding line. In overtype mode,
backspace() will not delete the new line.  Instead, when the cursor is at the
beginning of the line beep() is called.  If backspace() is called when the
cursor is at the beginning of the buffer, the beep() function is executed and
no other action is taken.

When the cursor is positioned beyond the end of the line (virtual space
enabled), executing the backspace() function performs a back-tab.  That is, the
cursor is moved to the closest tab setting to the left of its current position.

____________

Value returned: The backspace() function returns a non-zero value (TRUE) upon
successful completion. If the cursor is not moved, a value of zero (FALSE) is
returned.

____________

See also:  buffer_eol_string, buffer_flags


ΓòÉΓòÉΓòÉ 14.20.3. copy_to_scrap() ΓòÉΓòÉΓòÉ

copy_to_scrap()   Primitive

Purpose: Copy a portion of current buffer to scrap buffer.

____________

Syntax:  int copy_to_scrap()

____________

Description: The copy_to_scrap() function copies a character or region of text
from the current buffer to the scrap buffer.  Unlike the append_to_scrap()
function, copy_to_scrap() overwrites the previous contents of the scrap buffer.

If no block of text has been defined, the character at the cursor is copied to
the scrap buffer.

____________

Value returned:

When successful, the copy_to_scrap function returns a non-zero value (TRUE). If
for any reason the function can not be completed, a zero (FALSE) value will be
returned.

____________

See also:  delete_to_scrap(), append_to_scrap()


ΓòÉΓòÉΓòÉ 14.20.4. copy_to_scrap_key() ΓòÉΓòÉΓòÉ

copy_to_scrap_key()   PEL

Purpose: Copy or append portion of buffer to scrap.

____________

Syntax:  void copy_to_scrap_key([int append])

____________

Description: The copy_to_scrap_key() function is an enhanced version of the
copy_to_scrap() function intended for assignment to a keystroke.  It differs
from the copy_to_scrap() function in that it will either append or copy the
current selection to scrap and display a status message. If the append argument
is present and non- null the selection is appended to current contents of
scrap.  Otherwise scrap is overwritten.

____________

Value returned:

No useful value is returned by this function. buffer_original_filename,
attach_window_buffer(), edit_file()


ΓòÉΓòÉΓòÉ 14.20.5. cut() ΓòÉΓòÉΓòÉ

cut()   PEL

Purpose: Copy text to the scrap buffer and then delete it.

____________

Syntax:  int cut()

____________

Description: The cut() function copies a block of text to the scrap buffer in
the same manner as the copy_to_scrap() function, described above.  If no block
has been defined the line containing the cursor is copied to the scrap buffer.
With no block defined the character at the cursor position is copied.

After this is done, however, the cut() function deletes the copied text from
its original location in the edit buffer.  The text may then be re-inserted
elsewhere in the buffer through use of the insert_scrap() or paste() function.

This function has the effect of removing any selection marker (anchor) that was
used to mark the block to be deleted.  If any previous selections were made,
the most recent selection becomes active.

This function is synonymous with the delete_to_scrap() function.

____________

Value returned:

When successful, the cut() function returns a non-zero value (TRUE).  If for
any reason the function can not be completed, a zero (FALSE) value will be
returned.


ΓòÉΓòÉΓòÉ 14.20.6. delete_chars() ΓòÉΓòÉΓòÉ

delete_chars()   Primitive

Purpose: Delete text from the current edit buffer.

____________

Syntax:  int delete_chars([int num])

____________

Description: The delete_chars() function removes characters from the current
buffer.  The number of characters to delete is specified by the num argument.
If the num argument is not supplied the function deletes the selected block of
text if one has been marked.  Otherwise this function deletes a single
character.

____________

Value returned:

The delete_chars() function returns a non- zero value (TRUE) upon successful
completion.  If there are no characters for the delete function to remove, the
function will return a zero value (FALSE).


ΓòÉΓòÉΓòÉ 14.20.7. delete_prev_word() ΓòÉΓòÉΓòÉ

delete_prev_word()   PEL

Purpose:  To delete the word previous to the current cursor location.

____________

Syntax:   delete_prev_word( [int n] )

____________

Arguments:

o n - optional, the number of words to delete

Description: This function will delete the word previous to the curren cursor
location.  If the cursor is in the middle of a word, this function will delete
only to the beginning of the current word.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.20.8. delete_to_eol() ΓòÉΓòÉΓòÉ

delete_to_eol()   Primitive

Purpose: Delete from the cursor position to the end of the line.

____________

Syntax:  int delete_to_eol()

____________

Description: The delete_to_eol() function deletes all text from the cursor
position to the end of the line.  This includes any character under the cursor
position.  The end-of-line sequence is not deleted.

____________

Value returned: The value returned by delete_to_eol() is non-zero (TRUE) unless
there were no characters to delete, in which case a zero value (FALSE) is
returned.

____________

See also:  buffer_eol_string, delete_chars()


ΓòÉΓòÉΓòÉ 14.20.9. delete_to_scrap() ΓòÉΓòÉΓòÉ

delete_to_scrap()   Primitive

Purpose: Copy text to the scrap buffer and then delete it.

____________

Syntax:  int delete_to_scrap()

____________

Description: The delete_to_scrap() function copies a block of text to the scrap
buffer in the same manner as the copy_to_scrap() function, described above.
When no block has been defined the character at the cursor position is copied.

After this is done, however, the delete_to_scrap() function deletes the copied
text from its original location in the edit buffer.  The text may then be re-
inserted elsewhere in the buffer through use of the insert_scrap() function.

This function has the effect of removing any selection marker (anchor) that was
used to mark the block to be deleted.  If any previous selections were made,
the most recent selection becomes active.

For those who are familiar with the concepts of "cut and paste", this function
is analogous to "cut".  The insert_scrap() function serves as a "paste"
feature.

____________

Value returned: When successful, the delete_to_scrap() function returns a
non-zero value (TRUE). If for any reason the function can not be completed, a
zero (FALSE) value will be returned.


ΓòÉΓòÉΓòÉ 14.20.10. delete_word() ΓòÉΓòÉΓòÉ

delete_word()   PEL

Purpose: Delete word or words following cursor.

____________

Syntax:  void delete_word([int n])

____________

Description: The delete_word() function deletes from current position to the
next word.  The number of words to be deleted may be specified as the n
argument.  A word is defined as a series of non-whitespace characters
surrounded by whitespace. Whitespace includes spaces, tabs, newlines, beginning
and end of buffer.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.20.11. end_dump_mode ΓòÉΓòÉΓòÉ

end_dump_mode()   PEL

Purpose: Turns hex-dump mode off.

____________

Syntax: end_dump_mode()

____________

Description:  The end_dump_mode() function turns hex-dump mode off.

____________

Value returned: None.

____________

See also: window_flags, toggle_dump_mode(), begin_dump_mode(),
toggle_dump_window(), toggle_dump_side(), set_dump_format(), window_keymap,
mouse_event_offset, mouse_event_line, mouse_event_column, mouse_event_side,
mouse_event_digit, dump_digit, dump_bytes_per_line, default_dump_bytes_per_line


ΓòÉΓòÉΓòÉ 14.20.12. indent_columns() ΓòÉΓòÉΓòÉ

indent_columns()   Primitive

Purpose: Indent lines by adding whitespace to the left of text.

____________

Syntax:  int indent_columns([int num])

____________

Description: The indent_columns() function shifts a line or lines of text to
the right by inserting whitespace preceding the left end of text. If no marked
block of text has been defined, whitespace is added to the current line only.
If a block has been defined, each line of text in the block is indented. The
cursor position is changed as a result of this function if it is located within
the indented text.

If a column marked block of text has been defined, whitespace is added to each
line immediately to the left of the column at which the block begins.  When
other types of blocks exist, whitespace is added to the beginning of each line
in the block.

The number of spaces added to each line is determined by the value of the num
argument.  If the num argument is omitted, a value of 1 is assumed for that
argument.

____________

Value returned:

This function returns a non-zero value (TRUE) when successfully completed.  A
zero value (FALSE) is returned if an invalid value is supplied for the num
argument.


ΓòÉΓòÉΓòÉ 14.20.13. insert_key() ΓòÉΓòÉΓòÉ

insert_key()   Primitive

Purpose: Insert the character associated with a key into buffer.

____________

Syntax:  int insert_key([int char])

____________

Description: The insert_key() function inserts the character, whose ASCII value
is specified by the char argument, into the buffer at the cursor position.  If
the char argument is not supplied, the ASCII value of the most recently pressed
key is inserted.  The current position in the buffer is incremented to account
for this addition. The char argument may also be a key id obtained from a
function such as getkey(). Only the ASCII portion of the key id, which also
contains the scan code, is used.  The scan code is ignored.  If there is no
ASCII value to use an error occurs.

Most ordinary keyboard keys will call this function to insert the character
corresponding to the key pressed.  If word- wrap features are enabled, text
that exceeds the margin defined by wp_right_margin will be word-wrapped to the
following line.

____________

Value returned:

This function returns a non-zero or TRUE value unless the buffer_flags variable
is set to disallow edits to the buffer.  In this case a zero or FALSE value is
returned.

____________

See also:  delete_chars(), buffer_flags, insert_string()


ΓòÉΓòÉΓòÉ 14.20.14. insert_newline() ΓòÉΓòÉΓòÉ

insert_newline()   Primitive

Purpose: Insert end-of-line marker and move cursor to next line.

____________

Syntax:  int insert_newline()

____________

Description: The insert_newline() function inserts an end-of-line sequence
(buffer_eol_string) into the buffer at the current cursor position, and returns
the cursor to the beginning of the new line.

This function may also perform additional duties if the buffer_flags variable
indicate they are required.  When the WP_ENABLED bit of the buffer_flags is
set, the insert_newline() function honors the left-hand margin defined by the
wp_left_margin variable.  After the end-of- line marker has been inserted,
whitespace is added to the new line up to the column position contained in
wp_left_margin.

____________

Value returned:

This function will return a non-zero value except when the buffer_flags
variable indicates that the buffer may not be modified.  Under these
circumstances, the function returns zero.

____________

See also:  buffer_eol_string, buffer_flags, toggle_auto_indent


ΓòÉΓòÉΓòÉ 14.20.15. insert_scrap() ΓòÉΓòÉΓòÉ

insert_scrap()   Primitive

Purpose: Insert contents of scrap buffer at cursor position.

____________

Syntax:  int insert_scrap()

____________

Description: The insert_scrap() function inserts the contents of the scrap
buffer into the current buffer.  When no block of text has been selected the
text is inserted at the beginning of the line containing the cursor.
Otherwise, the text is inserted at the current cursor position.

After the insertion, the cursor is positioned at the end of the inserted text.
The contents of the scrap buffer are not modified or lost.

For those who are familiar with the concepts of "cut and paste", the
delete_to_scrap() function is analogous to "cut".  This function serves as a
"paste" feature.

____________

Value returned:

When successful, the insert_scrap() function returns a non-zero value (TRUE).
If for any reason the function can not be completed, a zero (FALSE) value will
be returned.

See also: cut(), paste().


ΓòÉΓòÉΓòÉ 14.20.16. open_line() ΓòÉΓòÉΓòÉ

open_line()   Primitive

Purpose: Inserts a new line following the current line.

____________

Syntax: int open_line()

____________

Description: The open_line() function opens a new line immediately below the
current one and positions the cursor at the beginning of that line.  The effect
of this function is always the same as moving the cursor to the end of the
current line and executing a insert_newline().  The insert_newline() function
is normally assigned to the  key unless auto- indent is on.

____________

Value returned: The value returned by open_line() is non-zero (TRUE) upon
success.  If the buffer is not editable the function will fail and return zero
or FALSE.


ΓòÉΓòÉΓòÉ 14.20.17. paste() ΓòÉΓòÉΓòÉ

paste()   PEL

Purpose: Insert contents of scrap buffer at cursor position.

____________

Syntax: int paste()

____________

Description: The paste() function is a synynom for the insert_scrap() function.
They function exactly the same.

____________

Value returned: TRUE if successful, FALSE if an error occured.


ΓòÉΓòÉΓòÉ 14.20.18. redo() ΓòÉΓòÉΓòÉ

redo()   Primitive

Purpose: Undoes the effects of a previous undo().

____________

Syntax: int redo([int index])

____________

Description: The redo() function restores the current buffer to a state prior
to an undo() function call.  If the index argument is not specified, redo()
reverses the effects of the most recent undo().  The index argument is a buffer
operation number.  When specified, redo() restores the buffer to its condition
when this operation number was the most recent edit.  The current operation
number may be obtained and recorded for later use by calling the undo_index()
function.  In order to be able to redo() an undo() there must be no intervening
edit operations.

This function is particularly useful when "undoing" a series of edits.  If one
or more desired edits are inadvertently undone, they may be "redone" through
the use of this function.  A series of undo() calls may be reversed by
successive calls to the redo() function.

____________

Value returned: The value returned by the redo() function is non- zero (TRUE)
if the edit operation is successfully redone.  A zero value (FALSE) is returned
if there was nothing to redo or if an error prevented the operation from being
redone.

____________

See also:   undo()


ΓòÉΓòÉΓòÉ 14.20.19. redo_index() ΓòÉΓòÉΓòÉ

redo_index()   Primitive

Purpose:  Queries the value of the redo index.

____________

Syntax:   int redo_index()

____________

Arguments: none.

Description: The redo_index() function is used to query the value of the redo
index.

____________

Value returned: Value of the redo index.


ΓòÉΓòÉΓòÉ 14.20.20. undo() ΓòÉΓòÉΓòÉ

undo()   Primitive

Purpose: Reverses the effects of a previous edit operation.

____________

Syntax: int undo([int index])

____________

Description: The undo() function restores the current buffer to its condition
previous to one or a series of recent edit or motion operations.  If the index
argument is not specified, undo() reverses the effects of the most recent edit.

Each operation on a buffer is assigned a sequential operation number.  The
index argument is one of these buffer operation numbers.  undo() uses this
argument to reverse the effects of all edits with operation numbers subsequent
to index.

The current operation number may be obtained and recorded for later use by
calling the undo_index() function.  A series of edit operations or commands may
also be reversed by successive calls to the undo() function.

If a desired edit operation is inadvertently undone, the redo() function allows
reversing the effect of an undo().

Operations which may be undone are stored, as they are executed, on an
"undo/redo stack".  Each buffer has its own undo stack.  For each call to the
undo() function, the most recent operation on the stack is reversed and the
current operation number for that buffer is decremented.

The operation that was undone is not lost, however, and is performed again if
redo() is called before further editing.  Whenever editing commences again the
contents of the stack beyond the current operation are lost.

____________

Value returned: The value returned by the undo() function is non- zero (TRUE)
if the edit operation is successfully undone.  A zero value (FALSE) is returned
if there was nothing to undo or if an error prevented an operation from being
undone.

____________

See also:   redo(), undo_index()


ΓòÉΓòÉΓòÉ 14.20.21. undo_index() ΓòÉΓòÉΓòÉ

undo_index()   Primitive

Purpose: Reports current operation number of undo/redo stack.

____________

Syntax: int undo_index()

____________

Description: The undo_index() function returns a value that the undo() or
redo() function can use to restore the current state of the buffer after
additional edits have been made.

Each operation on a buffer is assigned a sequential operation number.  This
function returns the number of the operation most recently performed. When
supplied as an argument to the undo() function, undo() reverses the effects of
all edits with operation numbers subsequent to this value.  After a series of
undo() calls, the redo() function can re-perform the series of operations up to
this value.

An example will clarify the use of these operation numbers:

You type the letters "a", "b" and "c" into a new, empty buffer.  This
represents three different edit operations.  Let us number them 1, 2, and 3.
You are not sure of the next letters you are about to type and you think you
may wish to return to the current state of the buffer if things don't work out.
You therefore execute the undo_index() function and store away the value it
gives you, which is the number 3.

Next you type the letters "x", "y" and "z".  We number these operations 4, 5,
and 6.  Already you are dissatisfied with the direction things are taking, so
you call the undo() function, supplying the value you received from
undo_index() as an argument.  Before doing so, however, you execute
undo_index() and store away the value ( 6 ) that it returns.  Soon the contents
of the buffer is again the letters "a", "b" and "c".  Remorse motivates you to
execute the redo() function, using the value from the second execution of
undo_index() as an argument.  The contents of the buffer is then "abcxyz".

____________

Value returned: The undo_index() function returns the number of the operation
most recently performed in the current buffer.


ΓòÉΓòÉΓòÉ 14.21. Time and Date ΓòÉΓòÉΓòÉ

The Time and Date function category is closely akin to the String manipulation
category since most times and dates are represented in strings. These functions
all use or produce a special time integer that contains the number of seconds
since 00:00:00 January 1, 1970.  Both dates and times are stored using this
type of integer.

The ctime() function supplies the time and date in the most verbose form. The
string returned by this function includes the complete time and date including
day of the week.  If you require just the date or just the time, the dos_date()
or dos_time() function, respectively, will probably serve your purpose better.
To create a time integer you use the time() function.  You supply the
individual values for year, month and so on in descending order of significance
until you reach the desired level of precision.  You need not specify elements
of lesser significance, such as seconds.

ctime()
          Supplies the time and date in string form.
dos_date()
          Converts encoded date into corresponding date string.
dos_time()
          Converts encoded time into time string.
time()
          Creates an encoded time value from elements.


ΓòÉΓòÉΓòÉ 14.21.1. ctime() ΓòÉΓòÉΓòÉ

ctime()  AWK   Primitive

Purpose: Supplies the time and date in string form.

____________

Syntax:  str ctime([int time])

____________

Description: The ctime() function interprets the date stored in the time
argument into a character string.  If the time argument is omitted the string
contains the current date and time.  The coding of the time argument is
described in detail in the description of the filetime() function.

The character string takes the following form:


    week _ daymonthdayhh : mm : ssyear

week_day is the first three characters of the day of the week and month is the
first three letters of the month.  day represents the day of the month.  This
is followed by the time of day, given in 24 hour format, and the year.  For
example:


  Wed Jul 05 15:03:22 1989

____________

Value returned: The value returned by the ctime() function is the string
containing the date and time.

____________

Compatibility:

This function is quite similar to the ctime function supported by major C
compilers except that the string returned does not contain a new-line sequence.


ΓòÉΓòÉΓòÉ 14.21.2. dos_date() ΓòÉΓòÉΓòÉ

dos_date()   Primitive

Purpose: Converts encoded date into corresponding date string.

____________

Syntax:  str dos_date([int datenum])

____________

Description: The dos_date() function converts the date encoded in the datenum
argument into a discernable string.  This string follows the form: MM/DD/YY.
When the datenum argument is omitted, the string produced contains the current
date.

____________

Value returned:

The value returned by the dos_date() function is the new string containing the
date.  If the datenum argument indicates a date prior to January 1, 1980 the
function will return an empty string.


ΓòÉΓòÉΓòÉ 14.21.3. dos_time() ΓòÉΓòÉΓòÉ

dos_time()   Primitive

Purpose: Converts encoded time into time string.

____________

Syntax:  str dos_time([int timenum])

____________

Description: The dos_time() function converts the time encoded in the timenum
argument into a discernable string.  This string follows the form:  HH:MM:SS.
If the datenum argument is omitted, the string produced contains the current
time.

____________

Value returned:

The value returned by the dos_time() function is the new string containing the
time.  If a negative value is supplied as an argument, the function will return
an empty string.


ΓòÉΓòÉΓòÉ 14.21.4. time() ΓòÉΓòÉΓòÉ

time()   Primitive

Purpose: Creates an encoded time value from elements.

____________

Syntax: int time([int yr [,mo [,day [,hr [,min [,sec]]]]]]) [,sec]]]]]])

____________

Description: The time() function assembles the components of a date, specified
as arguments to the function, into a timestamp integer.  The components that
may be specified are year, month, day, hour, minute and second.

The values allowed for these arguments are as follows:  The yr argument may be
any value from 1980 onward.  The mo argument may be in the range from 1 to 12.
The day argument may be from 1 to 31.  The hr argument may be from 0 to 23.
The min and sec arguments may each be from 0 to 59.

Each of the arguments to this function may optionally be omitted in order from
the least significant to the most significant.  If an argument is omitted, the
lowest allowable value for that argument is used.  If all arguments are
omitted, however, the function is treated as a current time inquiry.

____________

Value returned: The value returned by time() is the number of seconds since
00:00:00 GMT, January 1, 1970.


ΓòÉΓòÉΓòÉ 14.22. Toolbar ΓòÉΓòÉΓòÉ

create_toolbar()
          Creates a toolbar template
delete_toolbar()
          Removes a toolbar and frees all memory associated with it
delete_toolbaritem()
          To remove a toolbar item from a toolbar.
hide_toolbar()
          To hide a toolbar.
insert_toolbaritem()
          To insert a toolbar item(a button) onto the toolbar.
modify_toolbaritem()
          To modify the attributes of a particular toolbar button.
show_toolbar()
          Displays a toolbar on a window
toggle_toolbar()
          Sets or toggles the state of the toolbar.
toolbar_info()
          To provide information on a toolbar


ΓòÉΓòÉΓòÉ 14.22.1. create_toolbar() ΓòÉΓòÉΓòÉ

create_toolbar()   Primitive

Purpose: Creates a toolbar template

____________

Syntax: long create_toolbar([long parent])

____________

Description: The create_toolbar() function creates a blank toolbar template
sutable for placement of toolbar items.  Use the insert_toolbaritem() function
to place toolbar items on a toolbar.

The optional parent argument contains the window which will contain the
toolbar.  If no value is specified the main editor window will contain the
toolbar.  If parent is specified it must be a valid dialog box id returned from
one of the create_dialog functions.

____________

Value returned: The create_toolbar() function returns an id to the newly
created toolbar.  This value is later used to add items to the toolbar.


ΓòÉΓòÉΓòÉ 14.22.2. delete_toolbar() ΓòÉΓòÉΓòÉ

delete_toolbar()   Primitive

Purpose: Removes a toolbar and frees all memory associated with it

____________

Syntax: void delete_toolbar(long toolbar)

____________

Description: The delete_toolbar() function removes a toolbar from a window and
frees all associated memory used by the toolbar.  The toolbar id becomes
invalid after this call.

The toolbar argument contains the id of the toolbar to delete. This value must
be a value returned from the create_toolbar() function call.

____________

Value returned: This function does not return a value.


ΓòÉΓòÉΓòÉ 14.22.3. delete_toolbaritem() ΓòÉΓòÉΓòÉ

delete_toolbaritem()   Primitive

Purpose:  To remove a toolbar item from a toolbar.

____________

Syntax:   delete_toolbaritem( long tbhand, short itemid )

____________

Arguments:

o tbhand  - the handle of the toolbar to remove the item from
o itemid - the id of the item to remove

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.22.4. hide_toolbar() ΓòÉΓòÉΓòÉ

hide_toolbar()   Primitive

Purpose:  To hide a toolbar.

____________

Syntax:   hide_toolbar( long tbhand )

____________

Arguments:

o tbhand - the handle of the tooblar to hide

Description: The hide_toolbar() function hides a toolbar so it is no longer
visible. The memory associated with hide_toolbar() is not freed and the toolbar
id is still a valid toolbar id.  To make the toolbar visible call the
show_toolbar() function.

The toolbar argument contains the toolbar id of the toolbar which will be
hidden.

____________

Value returned:  none

____________

See also:create_toolbar(), show_toolbar()


ΓòÉΓòÉΓòÉ 14.22.5. insert_toolbaritem() ΓòÉΓòÉΓòÉ

insert_toolbaritem()   Primitive

Purpose:  To insert a toolbar item(a button) onto the toolbar.

____________

Syntax:   insert_toolbaritem( long tbhand, long itemid, long position, long
ResId, macroid action )

____________

Arguments:

o tbhand  - the handle of the toolbar to insert onto
o itemid  - the id of the button to insert
o position - the x position on the toolbar to insert the button
o ResId   - the id of the button resource
o action  - the function to execute when the button is pressed

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.22.6. modify_toolbaritem() ΓòÉΓòÉΓòÉ

modify_toolbaritem()   Primitive

Purpose:  To modify the attributes of a particular toolbar button.

____________

Syntax:   modify_toolbaritem( long tbhand, short item_id, short flag, [any
info] )

____________

Arguments:

o tbhand   -  the handle of the toolbar
o item_id  -  the id of the button
o flag    -  the attribute to set
o info    -  information specific to the flag

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.22.7. show_toolbar() ΓòÉΓòÉΓòÉ

show_toolbar()   Primitive

Purpose: Displays a toolbar on a window

____________

Syntax: void show_toolbar(long toolbar)

____________

Description: The show_toolbar() function displays the specified toolbar on it's
parent window.  The toolbar argument contains the toolbar id to display.

____________

Value returned: No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.22.8. toggle_toolbar() ΓòÉΓòÉΓòÉ

toggle_toolbar()   PEL

Purpose:  Sets or toggles the state of the toolbar.

____________

Syntax:   toggle_toolbar( enable )

____________

Arguments:

o enable - forced direction of toggle

Description: If the optional parameter on is specified, it forces the toolbar
to toggle either on if TRUE, or off if FALSE.  If the parameter is not
specified, the current state of toolbar is toggled.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.22.9. toolbar_info() ΓòÉΓòÉΓòÉ

toolbar_info()   Primitive

Purpose:  To provide information on a toolbar

____________

Syntax:   toolbar_info( long tbhand, [short flag, [short item_id, [short
noErrorMsg]]] )

____________

Arguments:

o tbhand    -  the handle of the toolbar to query; if zero, handle of editor
  window's toolbar is returned.
o flag     -  the type of info to query
o item_id    -  id of a toolbar item to query, not necessary for some flags
o noErrorMsg  -  do not display an error message if the item does not exist or
  the query is invalid.  Can be used to check for validity of an id.

Description: This function is used to query information about a toolbar, such
as querying the bitmap associated with a button, or checking whether a button
is currently enabled or disabled.  Valid queries are:

TB_IS_VISIBLE
          TRUE if toolbar is visible
TI_DISABLED
          TRUE if button is disabled, FALSE if not
TI_DOWN
          TRUE if button is down, FALSE if up
TI_ENABLED
          TRUE if button is enabled, FALSE if not
TI_FUNCTIONID
          funcid called when the button is pressed
TI_ITEMBITMAP
          bitmap associated with the button
TI_UP
          TRUE if button is up, FALSE if down

____________

Value returned: If successful, the value returned is the information requested,
otherwise, uninitialized is returned.


ΓòÉΓòÉΓòÉ 14.23. Types ΓòÉΓòÉΓòÉ

AutoIndent()
          Query the auto indent state of the given type.
Block()
          Query information about block style syntax highlighting items.
BufferFlags()
          Query the buffer flags used for a type.
Category()
          Query information about a syntax highlighting category for a type.
CommandLine()
          Query the command line for the compiler of a type.
CopyType()
          Copy all of the information associated with one type to another.
EscapeCharacter()
          Query the escape chracter defined for the given type.
Keyword()
          Query information about Keyword style syntax highlighting items.
LeftMargin()
          Query the position of the left margin.
Line()
          Query information about Line style syntax highlighting items.
Margins()
          Query the position of the margins.
MatchingPairs()
          Query the matching pairs defined for the given type.
RightMargin()
          Query the position of the right margin.
SetType()
          Add an extension-type association to the extensions array.
StyleDelimiters()
          Query the style delimiters defined for the given type.
Syntax()
          Query the state of syntax highlighting for a type.
Template()
          Query which template is assigned to a type.
add_syntax_category()
          Add a new syntax highlighting caegory to the specified type.
add_syntax_item()

add_type()
          Add a new type to the languages array.
load_factory_<type_name>_syntax()
          Load the factory default syntax highlighting items for <type_name>.
load_user_<type_name>_syntax()
          Load the user defined syntax highlighting items for <type_name>.
set_auto_indent()
          Define the auto indent status for a type.
set_buffer_flags()
          Define the buffer flags for a type.
set_case_sensitive()
          Define whether syntax highlighting for a type is case sensitive.
set_escape_character()
          Define the escape character used in syntax highlighting for a type.
set_expand_template()
          Define the template expansion status for a type.
set_left_margin()
          Define the left margin for a type.
set_margins()
          Define the margins for a type.
set_pairs()
          Define the matching pairs used for a type.
set_right_margin()
          Define the right margin for a type.
set_style_delimiters()
          Define the style delimiters used in syntax highlighting for a type.
set_syntax()
          Define the syntax highlighting status for a type.
set_tabs()
          Define the tab stops used for a type.


ΓòÉΓòÉΓòÉ 14.23.1. add_syntax_category() ΓòÉΓòÉΓòÉ

add_syntax_category()   PEL

Purpose:  Add a new syntax highlighting caegory to the specified type.

____________

Syntax:   add_syntax_category(str type, int index, str name, long fg, long bg)

____________

Arguments:

o type - name of type
o index - category number
o name - category name
o fg - foreground color for items in the category
o bg - background color for items in the category

Description: The add_syntax_category() function adds a new category to the list
of available categories for the specified type.  If index is less than zero,
the editor either adds a category of name "name" and assigns it a number, or if
"name" already exists, it is modified to have the new colors.  If index >= 0,
it is used as the category number, and the specified category is created or
modified.

____________

Value returned:

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.2. add_syntax_item() ΓòÉΓòÉΓòÉ

add_syntax_item()   PEL

Purpose:

____________

Syntax:   add_syntax_item(str type, int style, str item, long value, [long
MASK])

____________

Arguments:

o type - name of a type
o style - the kind of style the new item will be
o item - the syntax highlighting item being added
o value - the value to be assigned to the item
o MASK - mask applied to the existing item value and the new value

Description: The add_syntax_item() function adds a new item to the syntax
highlighting array for the given type or modifies an existing item. The style
argument is one of defined constants LINE, KEYWORD, or BLOCK. The item being
added must be  valid for the indicated style, as this function does not handle
validation.  All the information relevant to an item is passed in the value
parameter.  If a MASK is specified, the value parameter is MASKed over the
existing item value, otherwise the item value is replaced with "value".

____________

Value returned:

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.3. add_type() ΓòÉΓòÉΓòÉ

add_type()   PEL

Purpose:  Add a new type to the languages array.

____________

Syntax:   add_type(str name, [str compiler, [str template, [str tab_stobs, [str
margins, [str matching, [str escape_ch, [long flags, [int indent, [int syntax,
[str delimiters, [int sensitive, [int expand]]]]]]])

____________

Arguments:

o name - the name of the new type
o compiler - name of the compiler assigned to the type
o template - name of the template for the type
o tab_stobs - tab stop definition
o margins - string of left and right margins
o matching - the set of matching pairs
o escape_ch - character used as the escape character
o flags - flags to be used as buffer flags
o indent - auto indent flag
o syntax - syntax hightlighting flag
o delimiters - string of characters that delimts keywords
o sensitive - flag indicating if syntax highlighting items are case sensitive
o expand - flag for turning on template expansion

Description: The add_type() function adds a new type to the languages[] array.
All of the information provided in the function call is saved and applied to
buffers that have extensions mapped to the type.

____________

Value returned:

____________

See also:

o buffer_tabs
o languages[]


ΓòÉΓòÉΓòÉ 14.23.4. add_<type_name>_type() ΓòÉΓòÉΓòÉ

add_<type_name>_type()   PEL

Purpose:  Set up the default values for a specific type.

____________

Syntax:   add_<type_name>_type()

____________

Arguments:

Description: The add_<type_name>_name() functions set up the default values for
some predefined types including:

o add_awk_type()
o add_cobol_type()
o add_pascal_type()
o add_pel_type()
o add_rexx_type()
o add_vdiff_ref_type()
o add_vdiff_target_type()

____________

Value returned:

See also:


ΓòÉΓòÉΓòÉ 14.23.5. AutoIndent() ΓòÉΓòÉΓòÉ

AutoIndent()   PEL

Purpose:  Query the auto indent state of the given type.

____________

Syntax:   AutoIndent(str index)

____________

Arguments:

o index - extension or type name

Description: The AutoInent() function returns the auto indent status of the
given index.  The index may either be a type name or an extension.

____________

Value returned:

Value returned:TRUE if on, FALSE if off.

See also:

o auto_indent_mode
o languages[]


ΓòÉΓòÉΓòÉ 14.23.6. Block() ΓòÉΓòÉΓòÉ

Block()   PEL

Purpose:  Query information about block style syntax highlighting items.

____________

Syntax:   Block(str index, [str word, [long MASK]])

____________

Arguments:

o index - extension or type name
o word - syntax highlighting item
o MASK - information mask

Description: The Block() function returns the array of items that are block
styles of the given index.  The index may either be a type name or an
extension.  If the second parameter, word, is specified, information about the
block style "word" is returned.  The information returned depends on MASK.  If
not supplied, all information available for "word" is returned. Otherwise the
following table is used:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCATEGORY_MASK  ΓöéCategory number of word       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéITEM_MASK      ΓöéSyntax style index of word    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFLAG_MASK      ΓöéSpecial flags for advanced    Γöé
Γöé               Γöéhighlighting                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Value returned: Requested information or -1.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.7. BufferFlags() ΓòÉΓòÉΓòÉ

BufferFlags()   PEL

Purpose:  Query the buffer flags used for a type.

____________

Syntax:   BufferFlags(str index)

____________

Arguments:

o index - extension or type name

Description:

The BufferFlags() function returns the buffer flags of the given index.  These
flags are used whenever a buffer of this type is loaded.  The index may either
be a type name or an extension.

____________

Value returned: Buffer flags for the type.

See also:

o buffer_flags
o languages[]


ΓòÉΓòÉΓòÉ 14.23.8. Category() ΓòÉΓòÉΓòÉ

Category()   PEL

Purpose:  Query information about a syntax highlighting category for a type.

____________

Syntax:   Category(str index, [any word, [int flag]])

____________

Arguments:

o index - extension or type name
o word - category name or number
o flag - flag indicating what information to query

Description: The Category() function can be used to retrieve various
information from a type's array of syntax highlighting categories. The index
may either be a type name or an extension.  The word parameter may either be a
category name or a category number.  If it is not supplied, the entire array of
categories is returned.  The flag parameter indicates what information to
return on a particular category.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFlag   ΓöéInformation returned     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      ΓöéForeground color         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé2      ΓöéBackground color         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöéother  ΓöéCategory name or number  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Value returned: See above.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.9. CommandLine() ΓòÉΓòÉΓòÉ

CommandLine()   PEL

Purpose:  Query the command line for the compiler of a type.

____________

Syntax:   CommandLine(str index, [int expand, [str fname]])

____________

Arguments:

o index - compiler name, extension or type name
o expand - flag that forces the command line to be expanded
o fname - file name used in the expand command line

Description:

The CommandLine() function returns the command line used by the given index
when compile_buffer() is invoked.  The index may either be compiler name, type
name or an extension.  If the second parameter is TRUE, the command line is
expanded and the third parameter is used as the input file name.

____________

Value returned: Command line for the given index, or error code less than 0.

See also:

o compilers[]


ΓòÉΓòÉΓòÉ 14.23.10. CopyType() ΓòÉΓòÉΓòÉ

CopyType()   PEL

Purpose:  Copy all of the information associated with one type to another.

____________

Syntax:   CopyType(str type, str new_type)

____________

Arguments:

o type - type to copy from
o new_type - type to copy to

Description: The CopyType() function copies all of the information defined for
type to the corresponding fields of new_type.  If new_type does not exist, this
function will create it.

____________

Value returned:

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.11. EscapeCharacter() ΓòÉΓòÉΓòÉ

EscapeCharacter()   PEL

Purpose:  Query the escape chracter defined for the given type.

____________

Syntax:   EscapeCharacter(str index)

____________

Arguments:

o index - extension or type name

Description: The EscapeCharacter() function returns the escape character used
by the type.  Line styles preceded by the escape character and marked as being
escapable are not syntax highlighted.  The index may either be a type name or
an extension.

____________

Value returned:

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.12. get_case_sensitive() ΓòÉΓòÉΓòÉ

get_case_sensitive()   PEL

Purpose:  Query the state of the case sensitive flag of a type.

____________

Syntax:   int get_case_sensitive(str index)

____________

Arguments:

o index - file extension or type name

Description: The get_case_sensitive() function returns the state of the case
sensitive flag.  The flag is used to determine whether syntax highlighting
items are case sensitive or not.  The index parameter can be either a file
extension or a type name.

____________

Value returned: The state of the case sensitive flag for the type.

See also:

o case_insensitive
o languages[]


ΓòÉΓòÉΓòÉ 14.23.13. get_expand_template() ΓòÉΓòÉΓòÉ

get_expand_template()   PEL

Purpose:  Query the state of the template expansion of a type.

____________

Syntax:   int get_expand_template(str index)

____________

Arguments:

o index - file extension or type name

Description: The get_expand_template() function returns the state of template
exansion for the given index.  The index parameter can be either a file
extension or a type name.

____________

Value returned: The state of the case sensitive flag for the type.

See also:

o electric_mode
o expand_template()
o languages[]


ΓòÉΓòÉΓòÉ 14.23.14. Keyword() ΓòÉΓòÉΓòÉ

Keyword()   PEL

Purpose:  Query information about Keyword style syntax highlighting items.

____________

Syntax:   Keyword(str index, [str word, [long MASK]])

____________

Arguments:

o index - extension or type name
o word - syntax highlighting item
o MASK - information mask

Description: The Keyword() function returns the array of items that are keyword
styles of the given index.  The index may either be a type name or an
extension.  If the second parameter, word, is specified, information about the
keyword style "word" is returned.  The information returned depends on MASK.
If not supplied, all information available for "word" is returned. Otherwise
the following table is used:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCATEGORY_MASK  ΓöéCategory number of word       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéITEM_MASK      ΓöéSyntax style index of word    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFLAG_MASK      ΓöéSpecial flags for advanced    Γöé
Γöé               Γöéhighlighting                  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Value returned: Requested information or -1.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.15. LeftMargin() ΓòÉΓòÉΓòÉ

LeftMargin()   PEL

Purpose:  Query the position of the left margin.

____________

Syntax:   LeftMargin(str index)

____________

Arguments:

o index - extension or type name

Description: The LeftMargin() function returns the position of the left margin
for the specified index.  The index may either be a type name or an extension.

____________

Value returned: The left margin for the type or FALSE.

See also:


ΓòÉΓòÉΓòÉ 14.23.16. Line() ΓòÉΓòÉΓòÉ

Line()   PEL

Purpose:  Query information about Line style syntax highlighting items.

____________

Syntax:   Line(str index, [str word, [long MASK]])

____________

Arguments:

o index - extension or type name
o word - syntax highlighting item
o MASK - information mask

Description: The Line() function returns the array of items that are line
styles of the given index.  The index may either be a type name or an
extension.  If the second parameter, word, is specified, information about the
line style "word" is returned.  The information returned depends on MASK.  If
not supplied, all information available for "word" is returned. Otherwise the
following table is used:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCATEGORY_MASK  ΓöéCategory number of word       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéITEM_MASK      ΓöéSyntax style index of word    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéFLAG_MASK      ΓöéSpecial flags for advanced    Γöé
Γöé               Γöéhighlighting                  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéCOLUMN_MASK    ΓöéColumn word must begin in.    Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Value returned: Requested information or -1.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.17. load_factory_<type_name>_syntax() ΓòÉΓòÉΓòÉ

load_factory_<type_name>_syntax()   PEL

Purpose:  Load the factory default syntax highlighting items for <type_name>.

____________

Syntax:   load_factory_<type_name>_syntax()

____________

Arguments:

Description: The load_factory_<type_name>_syntax() functions are provided as a
base for syntax highlighting.  These functions are located in the
<type_name>.pel source files that are included with PREDITOR/2.  The first time
you load a file with an extension mapped to <type_name> and you have syntax
highlighting turned on, the corresponding load_user_<type_name>_syntax()
function is called.  Initially those functions contain a single call of the
load_factory_<type_name>_syntax() function.  These functions load each
individual syntax item with its color into an array that used for highlighting.

____________

Value returned:

See also:

o languages[]
o load_user_<type_name>_syntax()


ΓòÉΓòÉΓòÉ 14.23.18. load_user_<type_name>_syntax() ΓòÉΓòÉΓòÉ

load_user_<type_name>_syntax()   PEL

Purpose:  Load the user defined syntax highlighting items for <type_name>.

____________

Syntax:   load_user_<type_name>_syntax()

____________

Arguments:

Description: The load_user_<type_name>_syntax() functions load all of the
syntax itmes defined for <type_name>.  These functions are located in
language.pel and are written there whenever the information of an item of that
type is modified in the settings notebook. Initially these functions contain a
single call of the load_factory_<type_name>_syntax() function.

____________

Value returned:

See also:

o languages[]
o load_factory_<type_name>_syntax()


ΓòÉΓòÉΓòÉ 14.23.19. RightMargin() ΓòÉΓòÉΓòÉ

RightMargin()   PEL

Purpose:  Query the position of the right margin.

____________

Syntax:   RightMargin(str index)

____________

Arguments:

o index - extension or type name

Description: The RightMargin() function returns the position of the right
margin for the specified index.  The index may either be a type name or an
extension.

____________

Value returned: The right margin for the type or FALSE.

See also:


ΓòÉΓòÉΓòÉ 14.23.20. Margins() ΓòÉΓòÉΓòÉ

Margins()   PEL

Purpose:  Query the position of the margins.

____________

Syntax:   str Margins(str index)

____________

Arguments:

o index - extension or type name

Description: The Margins() function returns the positions of the margins for
the specified index.  In the returned string, the left margin precedes the
right margin and they are separated by a space.  The index may either be a type
name or an extension.

____________

Value returned: The margins for the type or FALSE.

See also:


ΓòÉΓòÉΓòÉ 14.23.21. MatchingPairs() ΓòÉΓòÉΓòÉ

MatchingPairs()   PEL

Purpose:  Query the matching pairs defined for the given type.

____________

Syntax:   str MatchingPairs(str index)

____________

Arguments:

o index - extension or type name

Description: The MatchingPairs() function returns the matching pairs defined
for the specified index.  In the returned string, pairs are separated by a
space, and opening and closing structures are separated by a space.  The index
may either be a type name or an extension.

____________

Value returned: The matching pairs for the type or FALSE.

See also:


ΓòÉΓòÉΓòÉ 14.23.22. set_auto_indent() ΓòÉΓòÉΓòÉ

set_auto_indent()   PEL

Purpose:  Define the auto indent status for a type.

____________

Syntax:   set_auto_indent(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new state of auto indent

Description: The set_auto_indent() function changes the state of auto indenting
for the given index to the value in flag.  Index may be either an extension or
a type name.

____________

Value returned:

See also:

o auto_indent_mode
o languages[]


ΓòÉΓòÉΓòÉ 14.23.23. set_buffer_flags() ΓòÉΓòÉΓòÉ

set_buffer_flags()   PEL

Purpose:  Define the buffer flags for a type.

____________

Syntax:   set_buffer_flags(str index, long flag)

____________

Arguments:

o index - extension or type name
o flag - new buffer flags for the type

Description: The set_buffer_flags() function changes the buffer flags for the
given index to the value in flag.  Index may be either an extension or a type
name.

____________

Value returned:

See also:

o buffer_flags
o languages[]


ΓòÉΓòÉΓòÉ 14.23.24. set_case_sensitive() ΓòÉΓòÉΓòÉ

set_case_sensitive()   PEL

Purpose:  Define whether syntax highlighting for a type is case sensitive.

____________

Syntax:   set_case_sensitive(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new buffer flags for the type

Description: The set_case_sensitive() function changes the state of case
sensitivity for the given index to the value in flag.  Index may be either an
extension or a type name.

____________

Value returned:

See also:

o case_insensitive
o languages[]


ΓòÉΓòÉΓòÉ 14.23.25. set_escape_character() ΓòÉΓòÉΓòÉ

set_escape_character()   PEL

Purpose:  Define the escape character used in syntax highlighting for a type.

____________

Syntax:   set_escape_character(str index, string flag)

____________

Arguments:

o index - extension or type name
o flag - new escape character for the type

Description: The set_escape_character() function changes the character used to
begin an escape sequence for the given index to the value in flag.  The escape
character can be place in front of line styles that are defined as escapable to
prevent them from being highlighted.  Index may be either an extension or a
type name.

____________

Value returned:

See also:

o escape_character
o languages[]


ΓòÉΓòÉΓòÉ 14.23.26. set_expand_template() ΓòÉΓòÉΓòÉ

set_expand_template()   PEL

Purpose:  Define the template expansion status for a type.

____________

Syntax:   set_expand_template(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new state of template expansion

Description: The set_expand_template() function changes the state of template
expansion for the given index to the value in flag.  Index may be either an
extension or a type name.

____________

Value returned:

See also:

o auto_indent_mode
o languages[]


ΓòÉΓòÉΓòÉ 14.23.27. set_left_margin() ΓòÉΓòÉΓòÉ

set_left_margin()   PEL

Purpose:  Define the left margin for a type.

____________

Syntax:   set_left_margin(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new value for the left margin

Description: The set_left_margin() function changes the left margin for the
given index to the value in flag.  Index may be either an extension or a type
name.

____________

Value returned:

See also:

o languages[]
o wp_left_margin
o wp_right_margin


ΓòÉΓòÉΓòÉ 14.23.28. set_right_margin() ΓòÉΓòÉΓòÉ

set_right_margin()   PEL

Purpose:  Define the right margin for a type.

____________

Syntax:   set_right_margin(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new value for the right margin

Description: The set_right_margin() function changes the right margin for the
given index to the value in flag.  Index may be either an extension or a type
name.

____________

Value returned:

See also:

o languages[]
o wp_left_margin
o wp_right_margin


ΓòÉΓòÉΓòÉ 14.23.29. set_margins() ΓòÉΓòÉΓòÉ

set_margins()   PEL

Purpose:  Define the margins for a type.

____________

Syntax:   set_margins(str index, string flag)

____________

Arguments:

o index - extension or type name
o flag - new value for the margins

Description: The set_margins() function changes the margins used in word
processing mode for the given index to the value in flag.  "flag" must be a
string of characters in which the left margin is followed by <space> and then
the right margin. Index may be either an extension or a type name.

____________

Value returned:

See also:

o languages[]
o wp_left_margin
o wp_right_margin


ΓòÉΓòÉΓòÉ 14.23.30. set_pairs() ΓòÉΓòÉΓòÉ

set_pairs()   PEL

Purpose:  Define the matching pairs used for a type.

____________

Syntax:   set_pairs(str index, string flag)

____________

Arguments:

o index - extension or type name
o flag - new matching pairs for the type

Description: The set_pairs() function changes the string defining the set of
matching pairs for the specified index.  The pairs specified in the flag
parameter are separated by a space, and opening and closing structures are
separated by a space.  The index may either be a type name or an extension.

____________

Value returned:

See also:

o matching_pairs
o languages[]


ΓòÉΓòÉΓòÉ 14.23.31. set_style_delimiters() ΓòÉΓòÉΓòÉ

set_style_delimiters()   PEL

Purpose:  Define the style delimiters used in syntax highlighting for a type.

____________

Syntax:   set_style_delimiters(str index, string flag)

____________

Arguments:

o index - extension or type name
o flag - new style delimiters for the type

Description: The set_style_delimiters() function changes the characters used to
delimit keywords for syntax highlighting.  The space and tab characters are
automatically used, so they do not need to be included in the string.  Index
may be either an extension or a type name.

____________

Value returned:

See also:

o escape_character
o languages[]


ΓòÉΓòÉΓòÉ 14.23.32. set_syntax() ΓòÉΓòÉΓòÉ

set_syntax()   PEL

Purpose:  Define the syntax highlighting status for a type.

____________

Syntax:   set_syntax(str index, int flag)

____________

Arguments:

o index - extension or type name
o flag - new state of syntax highlighting

Description: The set_syntax() function changes the state of syntax highlighting
for the given index to the value in flag.  Index may be either an extension or
a type name.

____________

Value returned:

See also:

o syntax_highlight
o languages[]


ΓòÉΓòÉΓòÉ 14.23.33. set_tabs() ΓòÉΓòÉΓòÉ

set_tabs()   PEL

Purpose:  Define the tab stops used for a type.

____________

Syntax:   set_tabs(str index, string flag)

____________

Arguments:

o index - extension or type name
o flag - new tab stops for the type

Description: The set_tabs() function changes the string defining the tab stops
for the specified index.  The index may either be a type name or an extension.

____________

Value returned:

See also:

o buffer_tabs
o languages[]


ΓòÉΓòÉΓòÉ 14.23.34. SetType() ΓòÉΓòÉΓòÉ

SetType()   PEL

Purpose:  Add an extension-type association to the extensions array.

____________

Syntax:   SetType(str ext, str type)

____________

Arguments:

o ext - file extension
o type - name of a type

Description: The SetType() function adds ext to the extensions[] array and maps
ext to the type "type".  The first character of "ext" must be a "." and "type"
must be a name that can be used as part of a function name i.e. it can only
include alphanumeric characters and the "_" character.

____________

Value returned:

See also:

o extensions[]
o Type()


ΓòÉΓòÉΓòÉ 14.23.35. Style() ΓòÉΓòÉΓòÉ

Style()   PEL

Purpose:  Query the style of a syntax highlighting item.

____________

Syntax:   int Style(str index, str item)

____________

Arguments:

o index - file extension or type name
o item - syntax highlighting item

Description: The Style() function returns the style of a syntax highlighting
item.  The index parameter can be either a file extension or a type name.

____________

Value returned: The function returns LINE, KEYWORD, BLOCK or FALSE.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.36. StyleDelimiters() ΓòÉΓòÉΓòÉ

StyleDelimiters()   PEL

Purpose:  Query the style delimiters defined for the given type.

____________

Syntax:   StyleDelimiters(str index)

____________

Arguments:

o index - extension or type name

Description: The StyleDelimiters function returns the characters that are
defined as delimiting keywords for the type.  In order for keywords to be
syntax highlighted, they must be surrounded by style delimiters.  Space and tab
are implicitly included.  The index may either be a type name or an extension.

____________

Value returned: The style delimiters for the type or FALSE.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.37. Syntax() ΓòÉΓòÉΓòÉ

Syntax()   PEL

Purpose:  Query the state of syntax highlighting for a type.

____________

Syntax:   int Syntax(str index)

____________

Arguments:

o index - extension or type name

Description: The Syntax() function returns whether syntax highlighting is
turned on for a type.  The index may either be a type name or an extension.

____________

Value returned: TRUE is syntax highlighting is on, FALSE otherwise.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.38. Tabs() ΓòÉΓòÉΓòÉ

Tabs()   PEL

Purpose:  Query the tab stops for a type.

____________

Syntax:   str Tabs(str index)

____________

Arguments:

o index - file extension or type name

Description: The Tabs() function returns the tab stops used by buffers of type
"index".  The index parameter can be either a file extension or a type name.

____________

Value returned: The tab stops used by buffers of type "index"

See also:

o buffer_tabs
o languages[]


ΓòÉΓòÉΓòÉ 14.23.39. Template() ΓòÉΓòÉΓòÉ

Template()   PEL

Purpose:  Query which template is assigned to a type.

____________

Syntax:   str Template(str index)

____________

Arguments:

o index - extension or type name

Description: The Template() function returns which template is assigned to a
type.  The index may either be a type name or an extension.

____________

Value returned: The name of the template used for template expansion for the
type.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.23.40. Type() ΓòÉΓòÉΓòÉ

Type()   PEL

Purpose:  Query the type associated with an extension.

____________

Syntax:   str Type(str ext)

____________

Arguments:

o ext - file extension

Description: The Type() function returns the type name associated with the
given extension.  The ext parameter must begin with a ".".

____________

Value returned: The type associated with the extension.

See also:

o languages[]


ΓòÉΓòÉΓòÉ 14.24. User Interface ΓòÉΓòÉΓòÉ

The User Interface category contains the functions and variables used in
creating menus, prompting the user and accessing a mouse.

Menus and Prompting

The functions provided for prompting the user are confirm() and prompt(). These
allow prompting for either a single character response or inputting a string,
respectively.

There are several lower level  used in creating and manipulating menus that are
also listed in this category.  Their use is normally limited to advanced users.
These functions include:  highlight_screen() and highlight_window()

Mouse Access

You access the mouse almost entirely through the use of variables.  Using a
mouse in extension language functions is easier than anticipated by most people
who have not previously programmed for a mouse.

You begin by determining if a working mouse is installed.  The mouse_available
variable will provide this information.  If the mouse is present, you declare
your intent to use the mouse by setting the mouse_enabled variable.  The next
step is to determine what appearance you will give the mouse.  Since the
PREDITOR/2 mouse has a software cursor, you may select the character and
attribute that indicates the current mouse position.  It is often preferable
just to change or complement the attribute of the existing character to
indicate the mouse position.  Whichever you choose to do, you control the
appearance of the mouse through the values of the mouse_cursor_mask and
mouse_display_mask variables.

You may use either of two different pairs of variables to mouse determine and
set the location of the mouse cursor.  These pairs of variables are mouse_
display_x/mouse_display_y and mouse_pixel_x/mouse_pixel_y.  While the mouse_
display_... variables describe the position of the mouse in lines and columns,
the mouse_pixel_... variables describe it in pixels.  Pixels provide a higher
resolution.  You may use either pair of these variables, even though you are in
text mode.  In contrast to variables such as current_line and current_column,
which begin the count with 1, both of these pairs of variables are zero origin.

Finally, you may determine what mouse buttons are depressed through the
mouse_buttons variable.  Alternately, you may wish to determine which mouse
buttons are depressed through the use of Events.  There are several  button
events described under the "Event Handling" category.

In addition, the functions window_border_contains(), window_contains() and
window_containing() will assist you in determining where the mouse is pointing.
The first two provide True/False answers to your assertions about a window
location and the third identifies which window is showing at a specified
location.

add_prompt_history()
          To add a string to a prompt history
beep()
          Emits a short tone from the speaker.
confirm()
          Prompts user and obtains a response.
current_history_item()
          To get an item from a history.
delete_history_item()
          To delete an item from a history list
display_errors()
          Parses an error file and places the results in a dialog.
error()
          Displays formatted output in dialog window.
flush_keyboard()
          Discards keyboard input currently waiting to be read.
getchar()
          Read an ASCII character from the keyboard.
getkey()
          Get a key code from the keyboard.
highlight_screen()
          Change the attribute of an area of text on the screen.
highlight_window()
          Change the attribute of an area of text in a window.
message()
          Displays formatted output in the Dialog window.
notify()
          Alerts user to a condition and allows response.
prompt()
          Presents a string for editing.
prompt_history()
          Prompt for string; remember previous strings.
toggle_pause()
          Toggles pausing on errors.
ungetkey()
          Return a character to the keyboard buffer.
warning()
          Displays formatted output in the Dialog window.


ΓòÉΓòÉΓòÉ 14.24.1. add_prompt_history() ΓòÉΓòÉΓòÉ

add_prompt_history()   PEL

Purpose:  To add a string to a prompt history

____________

Syntax:   add_prompt_history( str histName, str patt)

____________

Arguments:

o histName - the history to add to
o patt - the pattern to add

Description: The add_prompt_history() function adds patt to the end of
histName's history list.

____________

Value returned: The "patt"ern added to the list.


ΓòÉΓòÉΓòÉ 14.24.2. beep() ΓòÉΓòÉΓòÉ

beep()   Primitive

Purpose: Emits a short tone from the speaker.

____________

Syntax:  void beep()

____________

Description: The beep() function outputs a brief note from the speaker.  If
this sound does not meet with your approval or you wish to define a series of
different sounds, a new sound can be recorded in the beep_string() variable.

____________

Value returned:

No value is returned from this function.


ΓòÉΓòÉΓòÉ 14.24.3. confirm() ΓòÉΓòÉΓòÉ

confirm()   Primitive

Purpose: Prompts user and obtains a response.

____________

Syntax:  str confirm(str prompt, str responses)

____________

Description: The confirm() function displays the message provided in the prompt
argument.  It then reads the keyboard until one of the characters in the
responses string is typed or the user hits the escape key.  When a character
other than escape or the specified responses is typed, the function replies
with a beep().

The confirm function treats the characters in the responses argument in a
case-sensitive fashion.  This means that if both "Y" and "y" are acceptable
responses, both characters must be included in the string.

____________

Value returned:

The value returned by the confirm function is either a string containing the
response accepted or an empty string if the user pressed escape.


ΓòÉΓòÉΓòÉ 14.24.4. current_history_item() ΓòÉΓòÉΓòÉ

current_history_item()   PEL

Purpose:  To get an item from a history.

____________

Syntax:   current_history_item( str history, str index )

____________

Arguments:

o history  - history to index
o index   - index in the history

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.24.5. delete_history_item() ΓòÉΓòÉΓòÉ

delete_history_item()   PEL

Purpose:  To delete an item from a history list

____________

Syntax:   delete_history_item( str histName, str pattern )

____________

Arguments:

o histName - the name of the history
o pattern  - the item in the history to delete

Description:

____________

Value returned: TRUE  -  the delete was successful FALSE -  the pattern was not
found in the history


ΓòÉΓòÉΓòÉ 14.24.6. display_errors() ΓòÉΓòÉΓòÉ

display_errors()   PEL

Purpose:  Parses an error file and places the results in a dialog.

____________

Syntax:   void display_errors([str sourceFileName, str errorFileName, str
errorCompiler, bool saveFile, bool list_all, long dlgid]))

____________

Arguments:  sourceFileName = the name of the file the errors are for, it
defaults to the current buffer's filename,

errorFileName  = the name of the file that contains the errors, it defualt to
the same as sourceFileName, but with .ERR as the extension.

errorCompiler = the name of the compiler, it is looked up in the compiler
settings if not specified.

saveFile = a flag which if set, causes the errorFileName to be saved after the
errors are extracted, otherwise the errorFileName will be deleted.

list_all = a flag which if set, causes all lines in errorFileName to be placed
into the dialog. If it is not provided, then the value of list_all_output is
used.

dlgid = the handle of the dialog to place the errors, if it is not provided, a
new dialog will be created.

Description: The errorFileName file is parsed and the results are placed into a
compile list dialog.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.24.7. error() ΓòÉΓòÉΓòÉ

error()   Primitive

Purpose: Displays formatted output in dialog window.

____________

Syntax:  void error(str fmt [, any args,...])

____________

Description: The error() function prints a formatted message to the Dialog
window and aborts the PEL program currently processing.  If no dialog window
has been defined, a window pops up to display the message.  In this case the
editor pauses for a key to be typed before closing the window.  The output from
this function is suppressed if the variable message_level is 3.  The extension
language program, however, aborts regardless of how message_level is set.

The fmt and args arguments follow the argument form of the fprintf() function.

____________

Value returned: No useful value is returned by this function.

____________

See also:  message_level


ΓòÉΓòÉΓòÉ 14.24.8. flush_keyboard() ΓòÉΓòÉΓòÉ

flush_keyboard()   Primitive

Purpose: Discards keyboard input currently waiting to be read.

____________

Syntax:  int flush_keyboard()

____________

Description: The flush_keyboard() function empties the keyboard buffer of all
pending input.  This is often desirable before prompted input, to ensure that
perceived input is in response to the prompt.

____________

Value returned:

The value returned by the flush_keyboard() function is non-zero (TRUE) if there
were characters pending in the keyboard buffer. If there were no characters
pending, the function returns a zero (FALSE) value.


ΓòÉΓòÉΓòÉ 14.24.9. getchar() ΓòÉΓòÉΓòÉ

getchar()   Primitive

Purpose: Read an ASCII character from the keyboard.

____________

Syntax:  int getchar()

____________

Description: The getchar() function waits for a character to be received from
the keyboard and then returns its ASCII value or key code.

____________

Value returned:

If the key pressed has an ASCII value, that value will be returned.  If the
value returned is zero, a non-ASCII key has been pressed.  In this case,
calling getchar() again will obtain the key code.

____________

Example:

function read_key {
  local inchar
  inchar = getchar()
  if (inchar == 0 && keyboard_input_pending)
   inchar = shiftl(getchar(),8)
  return inchar
}

This example returns the input; either ASCII value or key code.

____________

See also:  getkey(), keyboard_input_pending


ΓòÉΓòÉΓòÉ 14.24.10. getkey() ΓòÉΓòÉΓòÉ

getkey()   Primitive

Purpose: Get a key code from the keyboard.

____________

Syntax:  int getkey()

____________

Description: The getkey() waits for a key to be pressed. It then returns the
key's key code.

____________

Value returned:

The getkey() function returns the key code of the key pressed.  Use the
int_to_ascii() function to convert the returned value to ASCII.

____________

See also:  getchar(), keyboard_input_pending, int_to_ascii()


ΓòÉΓòÉΓòÉ 14.24.11. highlight_screen() ΓòÉΓòÉΓòÉ

highlight_screen()   Primitive

Purpose: Change the attribute of an area of text on the screen.

____________

Syntax:  void highlight_screen(int x, y, wide, high, attr)

____________

Description: The highlight_screen() function changes the text attribute of a
specified area of the screen.  The area whose attribute is to be changed or
highlighted need not appear within any window.

The x and y arguments to this function are the screen column and line offsets.
These two arguments indicate where highlighting begins.

The wide and high arguments define the number of columns and lines that are to
be highlighted.  These arguments will normally be at least 1.

The attr argument is the attribute to be given to the text in the described
area. Permissible attribute values and their meanings are shown in a table in
the "Windowing" section in Part One of this manual.

____________

Value returned:

This function returns no useful value.

____________

See also:  highlight_window(),


ΓòÉΓòÉΓòÉ 14.24.12. highlight_window() ΓòÉΓòÉΓòÉ

highlight_window()   Primitive

Purpose: Change the attribute of an area of text in a window.

____________

Syntax:  void highlight_window(int x, y, wide, high, attr [, winid win])

____________

Description: The highlight_window() function changes the text attribute of a
specified area of a window.  The text whose attribute will change or be
highlighted is assumed to be in the current window unless the optional win
argument is supplied.

The x and y arguments to this function are column and line offsets from the
beginning of text in the window.  These two arguments indicate where
highlighting begins.  The variables window_text_x0 and window_text_y0 describe
the location where text begins in the window.

The wide and high arguments define the number of columns and lines that are to
be highlighted.  These arguments will normally be at least 1.

The attr argument is the attribute to be given to the text in the described
area. Permissible attribute values and their meanings are shown in a table in
the "Windowing" section in Part One of this manual.

____________

Value returned:

This function returns no useful value.

____________

See also:  highlight_screen().


ΓòÉΓòÉΓòÉ 14.24.13. message() ΓòÉΓòÉΓòÉ

message()   Primitive

Purpose: Displays formatted output in the Dialog window.

____________

Syntax: void message(str fmt [, any args,...])

____________

Description: The message() function prints a formatted message to the Dialog
window.  If no dialog window has been defined, a window pops up to display the
message. In this case the editor pauses for a key to be typed before closing
the window.  The output from this function is suppressed if the variable
message_level is greater than 0.

This function is primarily used to display informative messages, such as a
message telling the user that a task has been completed.  The fmt and args
arguments follow the argument specifications of the fprintf() function.

____________

Value returned: No useful value is returned by this function.

____________

See also:   message_level


ΓòÉΓòÉΓòÉ 14.24.14. notify() ΓòÉΓòÉΓòÉ

notify()   Primitive

Purpose: Alerts user to a condition and allows response.

____________

Syntax: void notify(str fmt [, any args,...])

____________

Description: The notify() function prints a formatted message to the Dialog
window.  If no dialog window has been defined, a window pops up to display the
message. In this case the editor pauses for a key to be typed before closing
the window.  The output from this function is suppressed if the variable
message_level is greater than 1.

This function is primarily used for responses to queries and to notify the user
of additional actions to take.  The messages printed by notify() normally need
to be seen by the user.  The fmt and args arguments follow the argument
specifications of the fprintf() function.

____________

Value returned: No useful value is returned by this function.

____________

See also:   message_level, message(), warning(), error().


ΓòÉΓòÉΓòÉ 14.24.15. prompt() ΓòÉΓòÉΓòÉ

prompt()   Primitive

Purpose: Presents a string for editing.

____________

Syntax: str prompt(str title [, str default], str helpid, bool highlight, long
parent)

Arguments:  message - describes the input requested.

default - initial value for the string.

helpid - help is displayed if you press [F1] or the help button.

highlight - highlight the default text.

parent - parent of the dialog.

____________

Description: The prompt() function requests a string value from the user.  An
initial value for this string may be supplied in the default argument.  The
message string describes the input requested and is displayed in the dialog
window.

This function is useful in obtaining values for assignment to editor string
variables, and also string arguments to functions.  It may be used to obtain a
directory to use or for inputting any string.

When editing an initial value, the first key struck by the user determines if
the string is to be edited or replaced.  If the key struck represents a
character, the string is re-initialized and that character becomes the sole
contents of the string. If instead the key struck is a cursor key  , or [Bksp]
the initial string is retained for editing.  The  key ends the editing process
and sends away the dialog window.

____________

Value returned: The value returned by the prompt() function is the string
specified by the user.


ΓòÉΓòÉΓòÉ 14.24.16. prompt_history() ΓòÉΓòÉΓòÉ

prompt_history()   PEL

Purpose: Prompt for string; remember previous strings.

____________

Syntax: str prompt_history(str index, str message, str default, int usehistory,
int highlight, str helpid )

____________

Description: Like prompt(), this function prompts for string input, but
pressing the up and down arrow keys allows it to recall previous responses.
The index argument is user-defined string with which previous responses are
associated.

For example, previous search string entries that were associated with the index
string SEARCH are available whenever SEARCH is specified again.

The message argument contains the prompt displayed to the user when the prompt
dialog box is displayed.  The default argument contains the default string to
be placed in the edit field of the dialog box.  The usehistory argument
contains a 1 if history is to be used.  The highlight argument contains a 1 if
you want the default text in the edit field to be highlighted.  The helpid
argument contains the help string index into the cpe.hlp file.

____________

Value returned: The prompt_history() function returns the string entered as a
response.


ΓòÉΓòÉΓòÉ 14.24.17. toggle_pause() ΓòÉΓòÉΓòÉ

toggle_pause()   PEL

Purpose: Toggles pausing on errors.

____________

Syntax: void toggle_pause([int force])

____________

Description: The toggle_pause() function toggles the state of the
pause_on_error variable.  Toggling pausing on ensures that each warning, error,
or informative message may be read before another is displayed. The
toggle_pause() function is particularly useful when you are testing
user-written functions that display a series of debugging messages.

The optional force argument allows you to force the pausing feature to the
condition you desire.  If the force argument is non-zero (TRUE), auto-indent is
turned on regardless of its previous condition. If force is zero (FALSE), this
feature is always turned off.

A synonym has been defined for this function, pe(). This synonym has a very
short name in order to facilitate its execution interactively.  This is done
through execute_function(), which is available through the  function in
standard keymaps.  By default, pausing is off.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.24.18. ungetkey() ΓòÉΓòÉΓòÉ

ungetkey()   Primitive

Purpose: Return a character to the keyboard buffer.

____________

Syntax: int ungetkey(int char)

____________

Description: The ungetkey() function pushes the character indicated by the char
argument back into the keyboard buffer.  This character will be the next
character available for later reading.  This may be a character read by either
the getchar() or the getkey() function.  In the case of extended keycodes, two
characters will actually be returned to the buffer.

Unlike the similar DOS function, more than one character may be un-read between
reads.

____________

Value returned: The value returned, upon successful completion, is the ASCII
value of the character re-inserted into the keyboard buffer.  This will be a
value identical to the char argument.


ΓòÉΓòÉΓòÉ 14.24.19. warning() ΓòÉΓòÉΓòÉ

warning()   Primitive

Purpose: Displays formatted output in the Dialog window.

____________

Syntax: void warning(str fmt [, any args,...])

____________

Description: The warning() function prints a formatted message to the Dialog
window.  If no dialog window has been defined, a window pops up to display the
message. In this case the editor pauses for a key to be typed before closing
the window.  The output from this function is suppressed if the variable
message_level is 3.

This function is primarily used to display messages that indicate a possible or
impending error.  The fmt and args arguments follow the argument specifications
of the fprintf() function.

____________

Value returned: No useful value is returned by this function.

____________

See also:   message_level


ΓòÉΓòÉΓòÉ 14.25. Version Control System ΓòÉΓòÉΓòÉ

prev_vdiff()
          Display the last vdiff results
pvcs()
          Toggles PVCS support features.
pvcs_vdiff()
          To perform a PVCS vdiff on two files and display its output in a
          graphical format.
system_pause()

toggle_file_locking()
          Toggles use of semaphore to ensure exclusive access.
toggle_pvcs()
          Toggles PVCS support features.


ΓòÉΓòÉΓòÉ 14.25.1. prev_vdiff() ΓòÉΓòÉΓòÉ

prev_vdiff()   PEL

Purpose:  Display the last vdiff results

____________

Syntax:   void prev_vdiff()

____________

Arguments: none.

Description: The prev_vdiff() function displays the results of the last vdiff
command without having to preform all of the processing again.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.25.2. pvcs() ΓòÉΓòÉΓòÉ

pvcs()   PEL

Purpose: Toggles PVCS support features.

____________

Syntax: void pvcs([int level])

____________

Description: The pvcs() function is a more tersely named synonym of the
toggle_pvcs() function.  It controls the level of automatic PVCS (Polytron
Version Control System) support provided by the editor.  The following values
have been defined for the level argument:

Label                    Value
PVCS_DISABLED            0
PVCS_ENABLE_GETS         1
PVCS_ENABLE_EMPTY_GETS   2
PVCS_ENABLE_GETS +       3
PVCS_ENABLE_EMPTY_GETS

PVCS_DISABLED (0) means that no automatic PVCS support is desired.
PVCS_ENABLE_GETS (1) indicates that if the user attempts to load a read-only
file the user is given the opportunity to retrieve a writable copy of the file
from its PVCS archive (logfile).  PVCS_ENABLE_EMPTY_GETS indicates that if the
user attempts to load a non-existent file the user is given the opportunity to
retrieve the file from its PVCS logfile. The PVCS_ENABLE_GETS and
PVCS_ENABLE_EMPTY_GETS values may be combined (3) to prompt the user for
retrieval of the file if it either doesn't exist or it is read-only.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.25.3. pvcs_vdiff() ΓòÉΓòÉΓòÉ

pvcs_vdiff()   PEL

Purpose:  To perform a PVCS vdiff on two files and display its output in a
graphical format.

____________

Syntax:   pvcs_vdiff()

____________

Arguments:  none

Description: This function will first display a dialog prompting you for the
PVCS files you wish to compare, the revision numbers, output orientation, etc.
After you choose your preference, it performs the verson difference and
displays those differences in a graphical format. Note: you must have called
pvcs() before calling this function in order to enable PVCS support.

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.25.4. system_pause() ΓòÉΓòÉΓòÉ

system_pause()   PEL

Purpose:

____________

Syntax:   system_pause(str cmd, short sys_flags )

____________

Arguments:

o cmd - command to be executed
o sys_flags - flags passed to the system command

Description: The system_pause() function executes cmd in a command shell and
then runs the pause command.  This allows the user to view the results of the
command before the shell goes away.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.25.5. toggle_file_locking() ΓòÉΓòÉΓòÉ

toggle_file_locking()   PEL

Purpose: Toggles use of semaphore to ensure exclusive access.

____________

Syntax: void toggle_file_locking([int on])

____________

Description: The toggle_file_locking() function enables, disables or toggles
the file locking feature.  This feature creates a special semaphore file in the
directory where each of the files are that have been loaded for editing.  If
the semaphore file already exists, the editor assumes the file is locked by
another user or editor session and the file is loaded as Read-Only.

The name of the semaphore file is the same as that of the file to be edited,
except that the third character of the extension is an ampersand, "&".
Extensions containing two or less characters are padded with underscores.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.25.6. toggle_pvcs() ΓòÉΓòÉΓòÉ

toggle_pvcs()   PEL

Purpose: Toggles PVCS support features.

____________

Syntax: void toggle_pvcs([int level])

____________

Description: The toggle_pvcs() function controls the level of automatic PVCS
(Polytron Version Control System) support provided by the editor.  The
following values have been defined for the level argument:

Label                    Value
PVCS_DISABLED            0
PVCS_ENABLE_GETS         1
PVCS_ENABLE_EMPTY_GETS   2
PVCS_ENABLE_GETS +       3
PVCS_ENABLE_EMPTY_GETS

PVCS_DISABLED (0) means that no automatic PVCS support is desired.
PVCS_ENABLE_GETS (1) indicates that if the user attempts to load a read-only
file the user is given the opportunity to retrieve a writable copy of the file
from its PVCS archive (logfile).  PVCS_ENABLE_EMPTY_GETS indicates that if the
user attempts to load a non-existent file the user is given the opportunity to
retrieve the file from its PVCS logfile.

The PVCS_ENABLE_GETS and PVCS_ENABLE_EMPTY_GETS values may be combined (3) to
prompt the user for retrieval of the file if it either doesn't exist or it is
read-only.

A more tersely named synonym for this function is the pvcs() function.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26. Windowing ΓòÉΓòÉΓòÉ

You use the functions in this category for creating, deleting, moving,
expanding and otherwise manipulating windows.

Some of both the windowing functions and variables use screen or window
coordinates.  It is important to note that these numbers differ from buffer
text line and column counts in that they are offsets or zero origin values. In
other words, the count begins with zero rather than one.

The variables in the Windowing category provide a wide range of information and
capabilities.  They allow setting appearance factors and setting appearance
defaults.  In addition, these variables describe window dimensions, text and
window locations, and indicate which window is current.

Creating and Deleting Windows

There are several functions in this group for creating and deleting windows.
There are three methods of creating windows.  The function create_window()
creates a window of arbitrary size and location.  These are called normal or
overlapping windows.  The create_tiled_window() function splits an existing
window in two either horizontally or vertically.  The final function with which
you can create a window is create_factory_window().  You use this function for
creating special purpose windows for which the current defaults would be
inappropriate.  The window is instead created using the rather vanilla internal
defaults.

The delete_window() function may be used to delete any window but the screen
area it occupied is not allocated to another window unless a contiguous window
exists.

When you delete the current window is deleted, the next window in the window
list and its buffer become active.  When deleting both the current buffer and
the current window the buffer should be deleted first.  If you delete the
window first, the current buffer will change, often resulting in deleting the
wrong buffer.

Window States

A window may exist in one of four states.  A window may be invisible, an icon,
normal size or expanded to fill the screen.  Functions are provided to switch
between window states and the window_flags variable can be examined to
determine which state applies to the current window.

The expand_window() function enlarges a window to the full-screen or zoomed
state.  It will not, however, overlap a single line dialog area at the top or
bottom of the screen, if one has been defined.

The restore_window() function restores the window to its normal state.  In the
normal state, the window occupies the dimensions originally reflected by the
window_height and window_width variables.

The collapse_window() function reduces a window to the icon state.  When in the
icon state, the window occupies a few columns of a single line, with a mnemonic
displayed in the block.

The hide_window() function makes a window invisible.  It still exists but does
not show on the screen even if there are no other windows to cover it up. This
is particularly useful for creating virtual windows that contain a menu or
something other than the usual buffer text.  Menus are described in the "User
Interface" chapter of this manual.

PREDITOR/2 remembers the  previously occupied by a window in its normal and
icon states.  This means that changing an icon that you tucked away in a corner
into a normal sized window may cause it to jump to center screen, if that were
its previous normal position.  Conversely, collapsing the normal window causes
its icon to jump back to the corner.

PREDITOR/2 does not attempt to remember the size and position of a full-screen
window, however.  This means that although you may resize or split a window
when it is in its full-screen state, the window's new size will not be
remembered when you change states.  Instead, the window will occupy the whole
screen each time it changes to the full-screen state.

Colors

Among the appearance variables are several variables that control the colors
applied to designated portions of windows and the screen.  There are also other
color variables that are not specific to individual windows.  You will find a
list of these variables in the "Editor System" chapter of this manual.
However, they follow the same usage rules as the color variables in this
chapter.

When you want to change the color of a window you previously created, you make
that window current and assign a value to the appropriate color_... variable.
If you want to set the color that will be used for all windows subsequently
created, just assign the desired value to the default_color_... equivalent.
For a more permanent change to the colors used for all edit windows, place
these default_color_... assignments in your local_setup() function and
recompile your function library.  For further details, read the "Custom
Configuration" section of the User's Manual.

adjust_window()
          Resize window using cursor keys.
arrange_windows()
          To arrange the MDI windows in a specified manner.
attach_window_buffer()
          Attaches an existing buffer to an existing window.
begin_dump_mode()
          Turns the hex-dump mode on.
cascade_buffers()
          To create a separate window for each buffer, and then cascade the
          windows.
collapse_window()
          Reduce a window to an icon.
compare_windows()
          To compare the buffers attached to two windows
create_factory_window()
          Creates a new window for system use.
create_tiled_window()
          Splits the current window into two windows.
create_window()
          Creates a new window at named coordinates.
delete_window()
          Dispose of a window.
delete_window_and_buffer()
          Deletes a window and its associated buffer.
delete_window_key()
          Delete window; make normal window current.
distance_to_window_bottom()
          To return the distance from the cursor to the top of the current
          window, in characters.
distance_to_window_left()
          To return the distance from the cursor to the left edge of the
          current window, in characters.
distance_to_window_middle()
          To return the distance from the cursor to the middle of the current
          window, in characters.
distance_to_window_right()
          To return the distance from the cursor to the right edge of the
          current window, in characters.
distance_to_window_top()
          To return the distance from the cursor to the bottom of the current
          window, in characters.
expand_window()
          Enlarge a window to fill the screen.
frame_window()
          Define or alter the dimensions of a window.
hide_window()
          Remove a window from the screen.
is_system_window()
          Tells if current window is for system use.
keep_windows_cascaded()
          Cascades all windows when the editor is resized.
keep_windows_tiled()
          keep_windows_tiled()
keep_windows_tiled_horizontal()
          Tiles all windows (horizontally) when the editor is resized.
keep_windows_tiled_vertical()
          Tiles all windows (vertically) when the editor is resized.
larger_window()
          Changes window to the next "larger" state.
next_window()
          Make subsequent window in list the current window.
next_window_key()
          To make the next window current.
organize_windows()
          Displays all defined windows as icons.
prev_window()
          Make preceding window on list the current window.
prev_window_key()
          To make the previous window current.
raise_window()
          Promote a window to the top of the list.
restore_window()
          Returns a window to its normal size.
set_dump_format()
          Sets the dump format in the WINDOW_CHARS bits of the window flags.
smaller_window()
          Changes current window to next smaller state.
split_window_horizontal()
          Split the current window horizontally.
split_window_vertical()
          Split the current window vertically.
switch_to_mdi()
          Switches windowing mode to mdi
switch_to_sdi()
          Switches windowing mode to sdi
tile_buffers()
          To create a separate window for each buffer, and then tile the
          windows.
tile_horizontal()
          Tiles all windows horizontally.
tile_vertical()
          Tiles all windows vertically.
toggle_dump_mode()
          Toggles hex-dump mode on and off.
toggle_dump_side()
          Toggles the WINDOW_NUM_SIDE window flag on and off.
toggle_dump_window()
          Toggles the hex-dump window flags on and off.
toggle_linenumbers()
          Turns on or off display of line numbers.
window_cascade()
          Cascade all windows.
window_tile()
          Tile all windows.
window_valid()
          Tells whether a window is currently defined.


ΓòÉΓòÉΓòÉ 14.26.1. adjust_window() ΓòÉΓòÉΓòÉ

adjust_window()   PEL

Purpose:  Resize window using cursor keys.

____________

Syntax:   void adjust_window()

____________

Description: The adjust_window() function allows adjusting the size of the
current window with cursor keys rather than with a mouse. A help message is
printed in the dialog window.  The user indicates acceptance of the new window
size by pressing Enter or returns the window to its unmodified size by pressing
Esc.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.2. arrange_windows() ΓòÉΓòÉΓòÉ

arrange_windows()   Primitive

Purpose:  To arrange the MDI windows in a specified manner.

____________

Syntax:   arrange_windows( int style )

____________

Arguments:

o style -  the style of arrangement to use, valid styles being: ICONIZE_WINDOWS
  CASCADE_WINDOWS TILE_WINDOWS

Description:

____________

Value returned: TRUE  -  arranged windows FALSE -  invalid style


ΓòÉΓòÉΓòÉ 14.26.3. attach_window_buffer() ΓòÉΓòÉΓòÉ

attach_window_buffer()   Primitive

Purpose: Attaches an existing buffer to an existing window.

____________

Syntax:  int attach_window_buffer(winid window, bufid buffer)

____________

Description: The attach_window_buffer() function connects a previously created
buffer to a previously created window.  The contents of the buffer may then be
viewed through the associated window.

The window and buffer arguments are the numeric ids returned by the functions
used to create the edit buffer and window respectively.

Attaching a window to a buffer breaks any previous association the window had
with another buffer.  A buffer, however, may have numerous windows attached to
it.  The buffer's association with other windows therefore remains unchanged.

If attach_window_buffer() is used to attach a buffer other than the currently
active buffer to the current window, the buffer becomes the current buffer.

The act of attaching a window to a buffer does not in itself make the contents
of the window visible nor does the window automatically become the current
window. The window may be hidden "under" another window.  In this case it will
not become visible until it is made the current window or the obscuring window
is moved or closed.

____________

Value returned:

Upon successful completion, attach_window_buffer() returns a non-zero value
(TRUE), otherwise a zero value (FALSE) is returned.

____________

See also:  edit_file(), create_buffer(), create_window()


ΓòÉΓòÉΓòÉ 14.26.4. begin_dump_mode() ΓòÉΓòÉΓòÉ

begin_dump_mode()    PEL

Purpose:  Turns the hex-dump mode on.

____________

Syntax:  begin_dump_mode(short fmt)

____________

Arguments:  fmt - sets the format of the number side.  The value for this
argument can be any one of the WINDOW_CHARS bits.  If you do not specify a
value for the fmt argument, the default value is WINDOW_DUMP (which is 0).

____________

Description:  The begin_dump_mode() function turns the hex_dump_mode on.

____________

See also:  window_flags, toggle_dump_mode(), end_dump_mode, toggle_dump_side(),
toggle_dump_window(), set_dump_format(), window_keymap, mouse_event_offset,
mouse_event_digit, dump_digit, dump_bytes_per_line, default_dump_bytes_per_line


ΓòÉΓòÉΓòÉ 14.26.5. cascade_buffers() ΓòÉΓòÉΓòÉ

cascade_buffers()   PEL

Purpose:  To create a separate window for each buffer, and then cascade the
windows.

____________

Syntax:   cascade_buffers()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.26.6. collapse_window() ΓòÉΓòÉΓòÉ

collapse_window()   Primitive

Purpose: Reduce a window to an icon.

____________

Syntax:  void collapse_window([winid window])

____________

Description: The collapse_window() function reduces the size of the window
identified by the window argument to the  "icon" state.  If no window argument
is specified, the current window is assumed.  If the window is already an icon,
the state is not changed.

The icon state is one of four states a window may occupy:  invisible, icon,
normal or zoomed.  When the window is zoomed, it takes up the entire screen.
In the normal state, the window occupies the dimensions originally reflected by
the window_height and window_width variables.  When in the icon state, the
window occupies a few columns of a single line, with a mnemonic displayed in
the block.  In the invisible state the window does not appear on the screen.

____________

Value returned:

No useful value is returned by the collapse_window function.

____________

See also:  expand_window(), hide_window(), restore_window()


ΓòÉΓòÉΓòÉ 14.26.7. compare_windows() ΓòÉΓòÉΓòÉ

compare_windows()   PEL

Purpose:  To compare the buffers attached to two windows

____________

Syntax:   compare_windows()

____________

Arguments:  none

Description: This function compares two buffers:  the current buffer and the
buffer attached to the next_window().  The cursor of each buffer is placed at
the location of the first difference in the buffers, or at the end of the
buffers if there is no difference.  The comparison starts at the current cursor
location in each buffer.

____________

Value returned: TRUE  -  the comparison was successful FALSE -  the comparison
was unsuccessful


ΓòÉΓòÉΓòÉ 14.26.8. create_factory_window() ΓòÉΓòÉΓòÉ

create_factory_window()   PEL

Purpose: Creates a new window for system use.

____________

Syntax:  winid create_factory_window([int x, y, wide, high [, flags]])

____________

Description: The create_factory_window() function creates a new window and
initializes the associated variables to the system internal defaults.  The
window is placed at the location defined by the x, y, wide and high arguments.

The x and y arguments indicate the column and line offset at which the editor
will locate the upper left corner of the window.  The wide and high arguments
indicate the number of columns and lines the window will occupy.  If any or all
of these arguments is omitted the largest possible window is created.  This
means that the window occupies the entire screen except for a single line at
the top or bottom for a dialog window, if defined.

The variables associated with the new window are initialized to internal
defaults whenever reasonable.  The function will not, for example, select
colors that will make the window effectively invisible against its background.
The value of the corresponding default_ variables are ignored.  If, however,
the optional flags argument is supplied, the window's window_flags variable is
initialized to that value rather than the internal value. This is useful if the
window to be used as a system window.  See the description of the
default_window_flags variable for details of the flags argument.  The Zoom
Status Field of the flags argument is always ignored.

The newly created window is inserted into the windows list in the position
immediately following the currently active window.  It is not automatically
made current nor is it attached to any buffer. The function
attach_window_buffer() is provided to define associations between windows and
buffers.

____________

Value returned:

create_factory_window() returns the numeric id that the editor system has given
to the newly created window.  This id should be stored for later use but never
modified. If the function fails a zero value is returned.

____________

See also:  edit_file(), create_window(), attach_window_buffer()


ΓòÉΓòÉΓòÉ 14.26.9. create_tiled_window() ΓòÉΓòÉΓòÉ

create_tiled_window()   PEL

Purpose: Splits the current window into two windows.

____________

Syntax:  void create_tiled_window(int pct [,int vert])

____________

Description: The create_tiled_window() function creates adjacent or "tiled"
windows by splitting the current window into two separate windows.  The two
windows occupy the screen area formerly occupied by the window that was split.
Both windows then view the current buffer.

The pct argument specifies what percent of the original window will continue to
be allocated to that window.  The balance is allocated to the new window.

The default action is to split the window horizontally.  When split
horizontally, the new window, the lower window, becomes current.  The vert
argument is used to split the window vertically.  If the vert argument is
supplied and is a value other than zero, windows are tiled vertically. The old
window is then on the left and the window on the right is current.

____________

Value returned:

No useful value is returned by this function.

____________

See also: current_window


ΓòÉΓòÉΓòÉ 14.26.10. create_window() ΓòÉΓòÉΓòÉ

create_window()   Primitive

Purpose: Creates a new window at named coordinates.

____________

Syntax:  winid create_window([int x, y, wide, high [, flags]])

____________

Description: The create_window() function creates a new window and initializes
the associated variables to the current editor system defaults.  The window is
placed at the location defined by the x, y, wide and high arguments.

The x and y arguments indicate the x and y offset in pixels at which the editor
will locate the upper left corner of the window.  The wide and high arguments
indicate the number of horizontal and vertical pixels the window will occupy.
If any or all of these arguments is omitted the largest possible window is
created.  This means that the window occupies the entire screen except for a
single line at the top or bottom for a dialog window, if defined.

The variables associated with the new window are initialized to the value of
the corresponding default_ variables.  If,  however, the optional flags
argument is supplied, the window's window_flags variable is initialized to that
value rather than the value of default_window_flags.  This is useful if the
window to be created is an  exception to the normal configuration.  See the
description of the default_window_flags variable for details of the flags
argument.  The Zoom Status Field of the flags argument is always ignored.

.This function is generally used only when you are able to supply the
dimensions of the window.

The newly created window is inserted into the windows list in the position
immediately following the currently active window.  It is not automatically
made current nor is it attached to any buffer.  The function
attach_window_buffer() is provided to define associations between windows and
buffers.

____________

Value returned: create_window() returns the numeric id that the editor  system
has given to the newly created window. This id should be stored for later use
but never modified.  If the function fails a zero value is returned.

See also: create_buffer(), attach_window_buffer(), create_factory_window(),
edit_file(), create_tiled_window(), delete_window()


ΓòÉΓòÉΓòÉ 14.26.11. delete_window() ΓòÉΓòÉΓòÉ

delete_window()   Primitive

Purpose: Dispose of a window.

____________

Syntax:  void delete_window([winid window])

____________

Description:  The delete_window() function discards the window described by the
window argument.  The window argument is a window id number assigned by the
editor system when the window was created.  If the window argument is omitted,
the current window is deleted.  The window id of the deleted window is no
longer valid.

Caution should be exercised when deleting active windows and buffers. When the
active window is deleted, the next window in the window list and its buffer
become active.  When deleting both the current buffer and the current window
the buffer should be deleted first.  If the window is deleted first the current
buffer will change, often resulting in the wrong buffer being deleted.

Unlike buffers, you may delete the last window.  You will then have very little
to look at.

____________

Value returned: No useful value is returned by the delete_window() function.


ΓòÉΓòÉΓòÉ 14.26.12. delete_window_and_buffer() ΓòÉΓòÉΓòÉ

delete_window_and_buffer()   PEL

Purpose: Deletes a window and its associated buffer.

____________

Syntax:  void delete_window_and_buffer([winid win])

____________

Description: The delete_window_and_buffer() function deletes the current buffer
and window or, if a window is specified as an argument, deletes the specified
window and associated buffer.  The function is useful for assignment to a key,
and also avoids the pitfall of deleting the wrong buffer when the window is
deleted first.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.13. delete_window_key() ΓòÉΓòÉΓòÉ

delete_window_key()   PEL

Purpose: Delete window; make normal window current.

____________

Syntax:  void delete_window_key()

____________

Description: Like delete_window(), the delete_window_key() function deletes
current window.  However, if the next window in the window list is a system
window, delete_window_key() does not allow it to become the current window as
the delete_window() function would.  Instead, this function makes the next
normal window current.  If there is no other normal window, no windows are
displayed. This behavior makes delete_window_key() more suitable for assignment
to a key than its relative, delete_window().

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.14. distance_to_window_ ΓòÉΓòÉΓòÉ

distance_to_window_   PEL

Purpose: Store distances from cursor to window extremities.

____________

Syntax:  int distance_to_window_...()

____________

Description: The several distance_to_window_ functions provide the distance in
columns or lines between the current cursor position and various window limits.

____________

Value returned:

The distance_to_window_ series of functions returns a value equal to the number
of left/right/up/down cursor motions necessary to move to the indicated window
extremity.

See also:  distance_to_window_left(), distance_to_window_right(),
distance_to_window_top(), distance_to_window_top()


ΓòÉΓòÉΓòÉ 14.26.15. distance_to_window_bottom() ΓòÉΓòÉΓòÉ

distance_to_window_bottom()   PEL

Purpose:  To return the distance from the cursor to the top of the current
window, in characters.

____________

Syntax:   distance_to_window_bottom()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.26.16. distance_to_window_left() ΓòÉΓòÉΓòÉ

distance_to_window_left()   PEL

Purpose:  To return the distance from the cursor to the left edge of the
current window, in characters.

____________

Syntax:   distance_to_window_left()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.26.17. distance_to_window_middle() ΓòÉΓòÉΓòÉ

distance_to_window_middle()   PEL

Purpose:  To return the distance from the cursor to the middle of the current
window, in characters.

____________

Syntax:   distance_to_window_middle()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.26.18. distance_to_window_right() ΓòÉΓòÉΓòÉ

distance_to_window_right()   PEL

Purpose:  To return the distance from the cursor to the right edge of the
current window, in characters.

____________

Syntax:   distance_to_window_right()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.26.19. distance_to_window_top() ΓòÉΓòÉΓòÉ

distance_to_window_top()   PEL

Purpose:  To return the distance from the cursor to the bottom of the current
window, in characters.

____________

Syntax:   distance_to_window_top()

____________

Arguments:  none

Description:

____________

Value returned:


ΓòÉΓòÉΓòÉ 14.26.20. expand_window() ΓòÉΓòÉΓòÉ

expand_window()   Primitive

Purpose: Enlarge a window to fill the screen.

____________

Syntax:  void expand_window([winid window])

____________

Description: The expand_window() function enlarges the size of the window
identified by the window argument to the "zoomed" state.  If no window argument
is specified, the current window is assumed.  If the window is already zoomed,
the state is not changed.

The zoomed or full-screen state is one of four states a window may occupy:
invisible, icon, normal or zoomed.  When the window is zoomed, it takes up the
entire screen.  In the normal state, the window occupies the dimensions
originally reflected by the window_height and window_width variables.  When in
the icon state, the window occupies a few columns of a single line, with a
mnemonic displayed in the block.  In the invisible state the window does not
appear on the screen.

____________

Value returned:

No useful value is returned by the expand_window() function.

____________

See also:  collapse_window(), hide_window(), restore_window()


ΓòÉΓòÉΓòÉ 14.26.21. frame_window() ΓòÉΓòÉΓòÉ

frame_window()   Primitive

Purpose: Define or alter the dimensions of a window.

____________

Syntax:  void frame_window([int x, y, wide, high [, winid win]])

____________

Description: The frame_window() function allows you to define the size and
location of a window. The window to be framed is designated by the win
argument.  The win argument must be a window previously created by a call to
create_window() or edit_file().  If this argument is omitted, the dimensions of
the current window are redefined.

The location and size of the window are defined by the x, y, wide and high
arguments.  The x and y arguments indicate the column and line offset at which
the editor will locate the upper left corner of the window.

The wide and high arguments indicate the number of columns and lines the window
will occupy.

If the x or y argument specifies a position off screen, the value is set to the
limit of that screen dimension.  When the value of the wide or high argument
would cause the window to extend off screen, the values of the x and y
arguments are reduced to allow the window to fit.  If this is not possible, the
window is truncated to fit the screen.

____________

Value returned:

No useful value is returned by the frame_window() function.


ΓòÉΓòÉΓòÉ 14.26.22. hide_window() ΓòÉΓòÉΓòÉ

hide_window()   Primitive

Purpose: Remove a window from the screen.

____________

Syntax:  void hide_window([winid window])

____________

Description: The hide_window() function changes the state of a window to
"invisible".  If no window argument is specified, the current window is
assumed.  If the window is already invisible the state is not changed. The
window is still defined but does not appear on the screen.  The window may be
made visible again through the use of the restore_window() function.

The invisible state is one of four states a window may occupy:  invisible,
icon, normal or zoomed.  When the window is zoomed, it takes up the entire
screen.  In the normal state, the window occupies the dimensions originally
reflected by the window_height and window_width variables.  When in the icon
state, the window is an icon (minimized).  In the invisible state the window
does not appear on the screen.  However, the window's position and shape
variables will reflect the same values as when the window is in its normal
state.

____________

Value returned:

No useful value is returned by the hide_window() function.

____________

See also:  expand_window(), collapse_window(), restore_window()


ΓòÉΓòÉΓòÉ 14.26.23. is_system_window() ΓòÉΓòÉΓòÉ

is_system_window()   PEL

Purpose: Tells if current window is for system use.

____________

Syntax:  int is_system_window()

____________

Description: The is_system_window() function reports whether the current window
has been defined as a system window.  It is useful when creating a function
that performs a task that should not be applied to system windows.

____________

Value returned:

Returns TRUE if the current window is a system window, else FALSE.


ΓòÉΓòÉΓòÉ 14.26.24. keep_windows_cascaded() ΓòÉΓòÉΓòÉ

keep_windows_cascaded()

Purpose: Cascades all windows when the editor is resized.

____________

Syntax: void keep_windows_cascaded()

____________

Description: The keep_windows_cascaded() function automatically cascades all
windows when you resize the editor.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.26.25. keep_windows_tiled() ΓòÉΓòÉΓòÉ

keep_window_tiled()

Purpose: Tiles all windows when the editor is resized.

____________

Syntax: void keep_windows_tiled()

____________

Description: The keep_windows_tiled() function automatically tiles all windows
when you resize the editor.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.26.26. keep_windows_tiled_horizontal() ΓòÉΓòÉΓòÉ

keep_windows_tiled_horizontal().

Purpose: Tiles all windows (horizontally) when the editor is resized.

____________

Syntax: void keep_windows_tiled_horizontal()

____________

Arguments: None.

____________

Description: When the editor window is resized, the
keep_windows_tiled_horizontal() function calls tile_horizontal().
Automatically, all windows are tiled horizontally.

____________

Value returned: None.

____________

See also: tile_horizontal()


ΓòÉΓòÉΓòÉ 14.26.27. keep_windows_tiled_vertical() ΓòÉΓòÉΓòÉ

Purpose: Tiles all windows (vertically) when the editor is resized.

____________

Syntax: void keep_windows_tiled_vertical()

____________

Arguments: None.

____________

Description: When the editor window is resized, the
keep_windows_tiled_vertical() function calls tile_vertical(). Automatically,
all windows are tiled vertically.

____________

Value returned: None.

____________

See also: tile_vertical()


ΓòÉΓòÉΓòÉ 14.26.28. larger_window() ΓòÉΓòÉΓòÉ

larger_window()   PEL

Purpose: Changes window to the next "larger" state.

____________

Syntax: void larger_window()

____________

Description: The larger_window() function expands the current window to normal
size if it is an icon or full- screen if it is normal sized.  If the window is
already full-screen this function has no effect.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.29. next_window() ΓòÉΓòÉΓòÉ

next_window()   Primitive

Purpose: Make subsequent window in list the current window.

____________

Syntax: winid next_window([str pattern [,int include_sys]])

____________

Description: The next_window() function may be used in two ways, depending on
whether a pattern is supplied.  In either case, next_window() is used to change
the currently active window.

When the pattern argument is not present or is an empty string, next_window()
may be used to increment forward through the windows list.

When a pattern is specified, next_window() will look forward through the
windows list for a window whose associated window_name matches the pattern
argument.  The pattern argument may contain wildcard characters as described in
the "Filename Matching" section of "General Operations" chapter of the User's
Manual.

If the pattern argument has been specified, you may optionally supply the
include_sys argument also. This argument is used to tell next_window() not to
skip system windows in moving through the windows list.  Normally, there is no
need to access system windows unless you are writing a menuing routine. If you
find the need, however, you may access system windows by supplying a non-zero
value as the include_sys argument.  You may then increment through the windows
list until you locate the system window of interest.  The following example
increments through the list of all windows:

  next_window("",1)

The current window is the last to be compared to the pattern argument.

____________

Value returned: This function always returns the numeric id of the current
window (current_window) as it exists after the operation.  If the function
fails, either because pattern does not match any subsequent window buffers or
there fewer than two windows in the list, the current window does not change.


ΓòÉΓòÉΓòÉ 14.26.30. next_window_key() ΓòÉΓòÉΓòÉ

next_window_key()   PEL

Purpose:  To make the next window current.

____________

Syntax:   next_window_key()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.26.31. organize_windows() ΓòÉΓòÉΓòÉ

organize_windows()   PEL

Purpose: Displays all defined windows as icons.

____________

Syntax: void organize_windows()

____________

Description: The organize_windows() function displays all defined windows in
rows as icons.  This can be useful when working with a large number of windows.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.32. prev_window() ΓòÉΓòÉΓòÉ

prev_window()   Primitive

Purpose: Make preceding window on list the current window.

____________

Syntax: winid prev_window([str pattern [, int include_sys]])

____________

Description: The prev_window() function may be used in two ways, depending on
whether the pattern argument is supplied.  In either case, prev_window() is
used to change the currently active window.

When the pattern argument is not present, prev_window() may be used to
increment backward through the windows list.

When pattern is supplied, prev_window() will jump backwards in the windows list
to a window whose buffer_name matches the pattern argument.  The pattern
argument may contain wildcard characters as described in the "Filename
Matching" section of "General Operation" chapter of the User's Manual.

If the pattern argument has been specified, you may optionally supply the
include_sys argument also. This argument is used to tell prev_window() not to
skip system windows in moving through the windows list.  Normally, there is no
need to access system windows unless you are writing a menuing routine. If you
find the need, however, you may access system windows by supplying a non-zero
value as the include_sys argument.  You may then increment through the windows
list until you locate the system window of interest.  The following example
increments through the list of all windows:

  prev_window("",1)

The current window is the last to be compared to the pattern argument.

____________

Value returned: This function always returns the numeric id of the current
window (current_window) as it exists after the operation.  If the function
fails, either because pattern does not match any subsequent window buffers or
there fewer than two windows in the list, the current window does not change.


ΓòÉΓòÉΓòÉ 14.26.33. prev_window_key() ΓòÉΓòÉΓòÉ

prev_window_key()   PEL

Purpose:  To make the previous window current.

____________

Syntax:   prev_window_key()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.26.34. raise_window() ΓòÉΓòÉΓòÉ

raise_window()   Primitive

Purpose: Promote a window to the top of the list.

____________

Syntax: void raise_window([winid window])

____________

Description: The raise_window() function promotes the window named by the
window argument to the top of the window list.  The window argument is a window
id number assigned by the editor system when the window was created.  If this
argument is omitted, the current window is raised.  Any other overlapping
windows on the screen will appear overlaid by this window.

As always, when the active window is changed, the buffer attached to the window
made current is then the active buffer.

____________

Value returned: No useful value is returned by the raise_window() function.


ΓòÉΓòÉΓòÉ 14.26.35. restore_window() ΓòÉΓòÉΓòÉ

restore_window()   Primitive

Purpose: Returns a window to its normal size.

____________

Syntax: void restore_window([winid window])

____________

Description: The restore_window() function returns a window to its normal size
regardless of its current state. If no window argument is specified, the
current window is assumed.  If the window is already at its normal size, the
state is not changed.

The normal state is one of four states a window may occupy:  invisible, icon,
normal or zoomed.  When the window is zoomed, it takes up the entire screen.
In the normal state, the window occupies the dimensions originally reflected by
the window_height and window_width variables.  When in the icon state, the
window occupies a few columns of a single line, with a mnemonic displayed in
the block.  In the invisible state the window does not appear on the screen.

____________

Value returned: No useful value is returned by the restore_window() function.


ΓòÉΓòÉΓòÉ 14.26.36. set_dump_format() ΓòÉΓòÉΓòÉ

set_dump_format()   PEL

Purpose: Sets the dump format in the WINDOW_CHARS bits of the window flags.

____________

Syntax: set_dump_format(short fmt)

____________

Arguments: fmt - sets the format of the number side.  The value for this
argument can be any one of the WINDOW_CHARS bits.  If you do not specify a
value for fmt, the default value is WINDOW_DUMP, which is 0.

____________

Description: The set_dump_format() function sets the dump format in the
WINDOW_CHARS bits of the window flags.

____________

Value returned: None.

____________

See also: window_flags, toggle_dump_mode(), begin_dump_mode(), end_dump_mode,
toggle_dump_window(), toggle_dump_side(), window_keymap, mouse_event_offset,
mouse_event_line, mouse_event_column, mouse_event_side, mouse_event_digit,
dump_digit, dump_bytes_per_line, default_dump_bytes_per_line


ΓòÉΓòÉΓòÉ 14.26.37. smaller_window() ΓòÉΓòÉΓòÉ

smaller_window()   PEL

Purpose: Changes current window to next smaller state.

____________

Syntax: void smaller_window()

____________

Description: The smaller_window() function reduces current window to normal
size if it is full-screen, or to icon if normal sized.  The function does
nothing if the window is already an icon.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.38. split_window_horizontal() ΓòÉΓòÉΓòÉ

split_window_horizontal()   PEL

Purpose: Split the current window horizontally.

____________

Syntax: void split_window_horizontal([int high])

____________

Description: The split_window_horizontal() function divides the current window
horizontally into two windows.  The high argument specifies the number of lines
to be reserved for the current window.  The remainder of the lines currently
allocated to the window will be given to the new window.  If the high argument
is omitted, this function splits the current window in half.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.39. split_window_vertical() ΓòÉΓòÉΓòÉ

split_window_vertical()   PEL

Purpose: Split the current window vertically.

____________

Syntax: void split_window_vertical([int wide])

____________

Description: The split_window_vertical() function divides the current window
vertically into two windows.  The wide argument specifies the number of columns
to be reserved for the current window.  The remainder currently allocated to
the window will be given to the new window.  If the wide argument is omitted,
this function splits the current window in half.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.40. switch_to_mdi() ΓòÉΓòÉΓòÉ

switch_to_mdi()   PEL

Purpose:  Switches windowing mode to mdi

____________

Syntax:   void switch_to_mdi()

____________

Arguments: none.

Description: The switch_to_mdi() function sets the windowing mode to mdi.  This
mode allows the user to open and display multiple windows.  If the editor is
already in mdi mode, this funcion has no effect.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.26.41. switch_to_sdi() ΓòÉΓòÉΓòÉ

switch_to_sdi()   PEL

Purpose:  Switches windowing mode to sdi

____________

Syntax:   void switch_to_sdi()

____________

Arguments: none.

Description: The switch_to_sdi() function sets the windowing mode to sdi.  This
mode allows the user to open and display only one window at a time.  If the
editor is already in sdi mode, this funcion has no effect.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.26.42. tile_buffers() ΓòÉΓòÉΓòÉ

tile_buffers()   PEL

Purpose:  To create a separate window for each buffer, and then tile the
windows.

____________

Syntax:   tile_buffers()

____________

Arguments:  none

Description:

____________

Value returned:  none


ΓòÉΓòÉΓòÉ 14.26.43. tile_horizontal() ΓòÉΓòÉΓòÉ

tile_horizontal()

Purpose: Tiles all windows horizontally.

____________

Syntax: void tile_horizontal()

____________

Description: When you call tile_horizontal(), all existing windows are tiled,
side by side.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.26.44. tile_vertical() ΓòÉΓòÉΓòÉ

tile_vertical()

Purpose: Tiles all windows vertically.

____________

Syntax: void tile_vertical()

____________

Description: When you call tile_vertical(), all existing windows are tiled
vertically, each one over the other.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 14.26.45. toggle_dump_mode() ΓòÉΓòÉΓòÉ

toggle_dump_mode()   PEL

Purpose:  Toggles hex-dump mode on and off.

____________

Syntax:  toggle_dump_mode(bool on, short format)

____________

Arguments: on - toggles the current state.  If this value is 0, the function is
toggled off.  If this value is not equal to zero, the function is toggled on.
If you do not specify a value for on, the current state is toggled.

fmt - sets the format of the number side.  The value for this argument can be
any one of the WINDOW_CHARS bits.  If you do not specify a value for the fmt
argument, the default is WINDOW_DUMP, which is 0.

____________

Description: The toggle_dump_mode() function toggles hex-dump mode on and off.
The difference between this function and the toggle_dump_window() function is
that it calls the begin_dump_mode() and end_dump_mode functions which perform
additional housekeeping tasks.

____________

Value returned:None.

____________

See also: begin_dump_mode(), end_dump_mode


ΓòÉΓòÉΓòÉ 14.26.46. toggle_dump_side() ΓòÉΓòÉΓòÉ

toggle_dump_side().   PEL

Purpose: Toggles the WINDOW_NUM_SIDE window flag on and off.

____________

Syntax: toggle_dump_side (bool on)

____________

Arguments:  on - toggles the current state.  If this value is 0, the function
is toggled off.  If this value is not equal to zero, the function is toggled
on.  If you do not specify a value for on, the current state is toggled.

____________

Description: The toggle_dump_side() function toggles the WINDOW_NUM_SIDE window
flag on and off.

____________

See also: window_flags, toggle_dump_mode(), begin_dump_mode(), end_dump_mode,
toggle_dump_side(), set_dump_format(), window_keymap, mouse_event_offset,
mouse_event_line, mouse_event_column, mouse_event_side, mouse_event_digit,
dump_digit, dump_bytes_per_line, default_dump_bytes_per_line


ΓòÉΓòÉΓòÉ 14.26.47. toggle_dump_window() ΓòÉΓòÉΓòÉ

toggle_dump_window().   PEL

Purpose: Toggles the hex-dump window flags on and off.

____________

Syntax: toggle_dump_window (bool on, short fmt)

____________

Arguments: on - toggles the current state.  If this value is 0, the function is
toggled off.  If this value is not equal to zero, the function is toggled on.
If you do not specify a value for on, the current state is toggled.

fmt - sets the format of the number side.  The value for this argument can be
any one of the WINDOW_CHARS bits.  If you do not specify a value, the default
is WINDOW_DUMP, which is 0.

____________

Description: The toggle_dump_window() function toggles the hex-dump window
flags on and off.

____________

Value returned: None.

____________

See also: window_flags, toggle_dump_mode(), begin_dump_mode(), end_dump_mode,
toggle_dump_side(), set_dump_format(), window_keymap, mouse_event_offset,
mouse_event_line, mouse_event_column, mouse_event_side, mouse_event_digit,
dump_digit, dump_bytes_per_line, default_dump_bytes_per_line


ΓòÉΓòÉΓòÉ 14.26.48. toggle_linenumbers() ΓòÉΓòÉΓòÉ

toggle_linenumbers()   PEL

Purpose: Turns on or off display of line numbers.

____________

Syntax: void toggle_linenumbers([int on])

____________

Description: The toggle_linenumbers() function turns on or off the display of
line numbers in the current window. When the on argument is zero, this feature
is turned off.  Other values for on turn it on.  When the on argument is
omitted the feature is toggled to its opposite condition.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.26.49. window_cascade() ΓòÉΓòÉΓòÉ

window_cascade()   PEL

Purpose:  Cascade all windows.

____________

Syntax:   void window_cascade()

____________

Arguments: none.

Description: The window_cascade() function arranges all open windows so they
are cascaded.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.26.50. window_tile() ΓòÉΓòÉΓòÉ

window_tile()   PEL

Purpose:  Tile all windows.

____________

Syntax:   void window_tile()

____________

Arguments: none.

Description: The window_tile() function arranges all open windows so they are
tiled.  This allows the user to see all of the windows at the same time without
having to hide them.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.26.51. window_valid ΓòÉΓòÉΓòÉ

window_valid()   Primitive

Purpose: Tells whether a window is currently defined.

____________

Syntax: int window_valid([winid win])

____________

Description: The window_valid() function reports whether the window id
indicated by win argument is defined.  If the argument is omitted, the function
tests the window id named by the current_window variable.

____________

Value returned: The value returned by this function is TRUE (non- zero) if the
window is valid.  Otherwise, the function returns FALSE (zero).


ΓòÉΓòÉΓòÉ 14.27. Word Processing ΓòÉΓòÉΓòÉ

The word processing category contains variables and functions that provide for
auto-indent and word-wrap capabilities.  These features may be applied to a
single paragraph in a single buffer or all active buffers.

The word processing features of PREDITOR/2 are useful for writing reports and
specifications.  In addition, they can simplify the task of making a long
source code comment aesthetically acceptable without throwing the rest of the
file into disarray.  PREDITOR/2 carries out these word processing features
using pure ASCII characters and standard end-of-line sequences.

You enable Word processing for a particular buffer by setting the WP_ENABLE bit
of the buffer_flags variable.  The toggle_wp() function has [been provided t o
perform this operation for you.  A tersely named synonym for this function,
wp(), is suitable for executing from the keyboard whenever you desire word
processing features.  The buffer_flags variable may be otherwise manipulated
using the set_flag_bits() function.

When you have word processing enabled, the paragraph you are editing is
continuously reformatted to conform to margins.  You define these margins with
the variables wp_left_margin and wp_right_margin.

When new line is added to the buffer as a result of word-wrap, the entire
contents of the word processing margin on the preceding line is copied to the
beginning of the new line.  This is particularly useful when you wish to have
each line begin with comment characters or some special character sequence.

Word processing need not be enabled to make use of word processing functions,
however.  You may wish to format a single paragraph using the wrap_paragraph()
function.  The indent_...() and outwent_...() functions listed here operate
independently of word processing.  These functions are useful for word
processing, however, as well as shifting blocks of source code to show nesting.

Auto-indent is somewhat similar to the word processing margin maintained when
word processing is in effect.  It causes the  not only to begin a new line but
also to copy any spaces and tabs at the beginning of the previous line to the
new line.  This has the effect of indenting the cursor to the position
immediately beneath the first non-whitespace character on the preceding line.

The auto-indent and word processing modes are completely independent, however.
You should select either auto-indent or word processing but not both.

There are also several functions in this category that allow manipulating the
case of characters.  The upper() function forces the characters in a marked
block to upper case while the lower() function does the opposite.  There are
also reverse(), which changes upper-case characters in a block to lower and
lower to upper, and capitalize() to make the first character of words in the
block upper-case.

capitalize()
          Makes first letter of words in block upper-case.
get_region_as_str()
          To read the highlighted region into a string
indent_space_maybe()
          Insert a space or indent selection
indent_tab_maybe()
          Insert a tab or indent the selection
indent_tabs()
          Indent lines by adding tabs to the left of text.
insert_auto_indent()
          Insert a new line and indent remaining text on the next line.
lower()
          Converts characters in a block to lower-case.
outdent_columns()
          Un-indent lines by deleting whitespace at left of text.
outdent_space_maybe()
          Delte a space or outdent selection
outdent_tab_maybe()
          Delete a tab or outdent the selection
outdent_tabs()
          Un-indent lines a specified number of tab stops.
reverse()
          Converts lower case to upper and upper to lower.
toggle_auto_indent()
          Toggles the auto-indent feature on or off.
toggle_wp()
          Toggles word processing mode.
toreverse()
          Reverses the case of characters in a string.
upper()
          Converts characters in a block to upper-case.
wp()
          Sets word processing mode options.
wrap_paragraph()
          Reformat a paragraph to conform to margins.


ΓòÉΓòÉΓòÉ 14.27.1. capitalize() ΓòÉΓòÉΓòÉ

capitalize()   PEL

Purpose: Makes first letter of words in block upper-case.

____________

Syntax:  void capitalize()

____________

Description: The capitalize() function converts the first character of each
word in the selected block of text to upper-case.  If no block has been
selected, only the word at the cursor is converted.  In this case, if the
cursor is in the middle of a word the character under the cursor is made
upper-case.

____________

Value returned:

No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.27.2. get_region_as_str() ΓòÉΓòÉΓòÉ

get_region_as_str()   PEL

Purpose:  To read the highlighted region into a string

____________

Syntax:   get_region_as_str( [str sep, [str term]] )

____________

Arguments:

o sep  - line separator for column selections
o term - terminator for column selections

Description: Read the characters in a region and return them as a string. For
columnar selections, the two parameters "sep" and "term" specify a string to be
used to separate each of the lines of the selection and to terminate the last
line of the selection, respectively.  A suggestion for the values of these
strings is " " and "\n" or, alternatively, "\n" and "\n".

____________

Value returned:  the highlighted region as a string


ΓòÉΓòÉΓòÉ 14.27.3. indent_space_maybe() ΓòÉΓòÉΓòÉ

indent_space_maybe()   PEL

Purpose:  Insert a space or indent selection

____________

Syntax:   void indent_space_maybe()

____________

Arguments: none

Description: The indent_space_maybe() function indents the current selection by
a column.  If no selection has been made, a space is inserted at the cursor
position.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.27.4. indent_tab_maybe() ΓòÉΓòÉΓòÉ

indent_tab_maybe()   PEL

Purpose:  Insert a tab or indent the selection

____________

Syntax:   void indent_tab_maybe()

____________

Arguments: none

Description: The indent_tab_maybe() function indents the current selection by a
tabstop.  If no selection has been made, a tab is inserted at the cursor
position.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.27.5. indent_tabs() ΓòÉΓòÉΓòÉ

indent_tabs()   Primitive

Purpose: Indent lines by adding tabs to the left of text.

____________

Syntax:  int indent_tabs([int num])

____________

Description: The indent_tabs() function indents a line or lines of text by
inserting a specified number of tabs preceding the left end of text.  If no
marked block of text has been defined, tabs are added to the current line only.
If a block has been defined, each line of text in the block is indented by
adding tabs.  The cursor position is changed as a result of this function if it
is located within the indented text.

If a column marked block of text has been defined, whitespace is added to each
line immediately to the left of the column at which the block begins.  When
other types of blocks exist, whitespace is added to the beginning of each line
in the block.

The number of tabs added to each line is determined by the value of the num
argument.  If the num argument is omitted, a value of 1 is assumed for that
argument.

____________

Value returned:

This function returns a non-zero value (TRUE) when successfully completed.  A
zero value (FALSE) is returned if an invalid value is supplied for the num
argument.


ΓòÉΓòÉΓòÉ 14.27.6. insert_auto_indent() ΓòÉΓòÉΓòÉ

insert_auto_indent()   PEL

Purpose:  Insert a new line and indent remaining text on the next line.

____________

Syntax:   void insert_auto_indent()

____________

Arguments: none.

Description: The insert_auto_indent() function inserts a new line and moves the
remaining text of the current line to the next line.  The new line is indented
to the same column as the previous nonblank line.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.27.7. lower() ΓòÉΓòÉΓòÉ

lower()   PEL

Purpose: Converts characters in a block to lower-case.

____________

Syntax: void lower()

____________

Description: The lower() function converts all upper-case letters in a selected
block of text to lower-case. If no block has been selected the character at the
cursor is converted.  Numbers punctuation and white-space in the block are not
modified by this function.

____________

Value returned: No useful value is returned by this function.

____________

See also:   tolower()


ΓòÉΓòÉΓòÉ 14.27.8. outdent_columns() ΓòÉΓòÉΓòÉ

outdent_columns()   Primitive

Purpose: Un-indent lines by deleting whitespace at left of text.

____________

Syntax: int outdent_columns([int num])

____________

Description: The outdent_columns() function shifts text a specified number of
columns to the left.  This is done by removing spaces or tabs from the
whitespace preceding text in a line or lines of text.  The cursor moves with
the text to maintain its relative position.

If a column marked block of text has been defined, whitespace is removed from
each line immediately to the left of the column at which the block begins. When
other types of blocks exist, whitespace is removed from the beginning of each
line in the block.

The number of columns to shift each line is determined by the value of the num
argument.  If the num argument is omitted, a value of 1 is assumed for that
argument.

____________

Value returned: This function returns a non-zero value (TRUE) when successfully
completed.  A zero value (FALSE) is returned if there is no whitespace to the
left of text or an invalid value is supplied for the num argument.


ΓòÉΓòÉΓòÉ 14.27.9. outdent_space_maybe() ΓòÉΓòÉΓòÉ

outdent_space_maybe()   PEL

Purpose:  Delte a space or outdent selection

____________

Syntax:   void outdent_space_maybe()

____________

Arguments: none

Description: The outdent_space_maybe() function outdents the current selection
by a column.  If no selection has been made, a space is deleted before the
cursor position.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.27.10. outdent_tab_maybe() ΓòÉΓòÉΓòÉ

outdent_tab_maybe()   PEL

Purpose:  Delete a tab or outdent the selection

____________

Syntax:   void outdent_tab_maybe()

____________

Arguments: none

Description: The outdent_tab_maybe() function outdents the current selection by
a tabstop.  If no selection has been made, a tab is deleted before the cursor
position.

____________

Value returned: none.


ΓòÉΓòÉΓòÉ 14.27.11. outdent_tabs() ΓòÉΓòÉΓòÉ

outdent_tabs()   Primitive

Purpose: Un-indent lines a specified number of tab stops.

____________

Syntax: int outdent_tabs([int num])

____________

Description: The outdent_tabs() function shifts text a specified number of tab
stops to the left.  This is done by removing spaces or tabs from the whitespace
preceding text in a line or lines of text.  The cursor moves with the text to
maintain its relative position.

If a column marked block of text has been defined, whitespace is removed from
each line immediately to the left of the column at which the block begins. When
other types of blocks exist, whitespace is removed from the beginning of each
line in the block.

The number of tabs stops to shift each line is determined by the value of the
num argument.  If the num argument is omitted, a value of 1 is assumed for that
argument.

____________

Value returned: This function returns a non-zero value (TRUE) when successfully
completed.  A zero value (FALSE) is returned if there is no whitespace to the
left of text or an invalid value is supplied for the num argument.


ΓòÉΓòÉΓòÉ 14.27.12. reverse() ΓòÉΓòÉΓòÉ

reverse()   PEL

Purpose: Converts lower case to upper and upper to lower.

____________

Syntax: void reverse()

____________

Description: The reverse() function reverses the case of the selected portion
of the buffer.  Any character which was lower case is converted to upper and
any upper case character becomes lower.  If no selection mark has been defined
the case of the character under the cursor is reversed.

The VI emulation package uses this function to allow converting a specified
number of characters.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.27.13. toggle_auto_indent() ΓòÉΓòÉΓòÉ

toggle_auto_indent()   PEL

Purpose: Toggles the auto-indent feature on or off.

____________

Syntax: void toggle_auto_indent([int force])

____________

Description: The toggle_auto_indent() function toggles the state of
PREDITOR/2's auto-indent feature.  This function therefore affects the action
of the  key.

When auto-indent is on, a special function is assigned to the  and   keys.
These functions copy a like amount of whitespace preceding the text on the
previous line to new lines.  If the previous line does not contain any
printable characters, nothing is copied to the new line.  When auto-indent is
off, the function usually assigned to the  key, insert_newline(), merely begins
a new line by inserting the new line sequence.

The optional force argument allows you to force the auto-indent feature to the
condition you desire. If the force argument is non-zero (TRUE), auto- indent is
turned on regardless of its previous condition.  If force is zero, this feature
is always turned off.

Auto-indent has some similarities to the word processing margin maintained when
word processing is in effect.  These two modes are completely independent,
however.  You should select either auto-indent or word processing but not both.

By default, auto-indent is off.  It may, however, be turned on by the emulation
mode you have selected.

This function has a synonym, ai().  A very short name has been selected for
this synonym to facilitate its execution interactively.  This is done through
execute_function(), which in standard keymaps is available by pressing the[F10]
key.

____________

Value returned: No useful value is returned by this function.

____________

See also:   buffer_flags, insert_newline()


ΓòÉΓòÉΓòÉ 14.27.14. toggle_wp() ΓòÉΓòÉΓòÉ

toggle_wp()   PEL

Purpose: Toggles word processing mode.

____________

Syntax: void toggle_wp([int force])

____________

Description: The toggle_wp() function toggles the use of the editor's word
processing features.  This is done by changing the WP_ENABLED bit of the
buffer_flags variable.

When the WP_ENABLED bit is on, word-wrap features are applied to the current
paragraph of the buffer. As text is added or deleted from the paragraph, the
lines of text are reformatted as necessary to conform to word processing
margins (see wp_left_margin and wp_right_margin).  When reformatting a line of
text results in no changes to that line, the editor assumes that the rest of
the paragraph is already in proper format.

When word processing is on and a new line is added to the buffer the entire
contents of the word processing margin on the preceding line is copied to the
beginning of the new line.  This is particularly useful when you wish to have
each line begin with comment characters or some special character sequence.

The optional force argument allows you to force the word-processing feature to
the condition you desire.  If the force argument is non-zero (TRUE),
auto-indent is turned on regardless of its previous condition.  If force is
zero (FALSE), this feature is always turned off.

The Auto-indent feature of the editor is somewhat similar to the word
processing margin.  These two modes are completely independent, however.  You
should select either auto-indent or word processing but not both.

The synonym wp() has been defined for this function.  The very short name
chosen for this synonym facilitates its execution interactively. This is done
through execute_function(), which is available in standard keymaps through
pressing the  key.  By default, word processing is off.

The subject of word processing is discussed in greater detail in the "Word
Processing" chapter in Part One of this manual.

____________

Value returned: No useful value is returned by this function.


ΓòÉΓòÉΓòÉ 14.27.15. toreverse() ΓòÉΓòÉΓòÉ

toreverse()   PEL

Purpose: Reverses the case of characters in a string.

____________

Syntax: str toreverse(str string)

____________

Description: The toreverse() function creates a string in which the upper case
characters in the string argument are converted to lower case and the lower
case characters to upper case.  This means that characters in the range
"a".."z" become the corresponding character in the range "A".."Z" and vice
versa.

____________

Value returned: The value returned by the toreverse() function is the newly
created string containing the converted characters.

____________

See also:   reverse()


ΓòÉΓòÉΓòÉ 14.27.16. upper() ΓòÉΓòÉΓòÉ

upper()   PEL

Purpose: Converts characters in a block to upper-case.

____________

Syntax: void upper()

____________

Description: The upper() function converts all lower-case letters in a selected
block of text to upper-case. If no block has been selected the character at the
cursor is converted.  Numbers punctuation and white-space in the block are not
modified by this function.

____________

Value returned: No useful value is returned by this function.

____________

See also:   toupper()


ΓòÉΓòÉΓòÉ 14.27.17. wrap_paragraph() ΓòÉΓòÉΓòÉ

wrap_paragraph()   Primitive

Purpose: Reformat a paragraph to conform to margins.

____________

Syntax: int wrap_paragraph()

____________

Description: The wrap_paragraph() function fills and wraps text in the current
paragraph in units of words.  When completed, the text in the paragraph
conforms to the limits defined by the wp_left_margin and wp_right_margin
variables.

If a marked block has been defined, the text is reformatted from the beginning
of the marked block to the end of the last line containing marked text. If
column marking is used, the wp_left_margin and wp_right_margin variables will
be set to the column boundaries used.

Only text to the right of the wp_left_margin will be formatted.  If text exists
in the left-hand margin, its position will not be altered.  New lines may be
created as the result of wrapping text.  When this happens, the whitespace or
text occurring in the left margin of the preceding line is duplicated at the
beginning of the new line.

Word-wrap and word processing features of the editor are discussed in greater
detail in the "Word Processing" chapter in Part One of this manual.

____________

Value returned: This function returns a non-zero value upon successful
completion.  If an error occurs, a zero value is returned.


ΓòÉΓòÉΓòÉ 15. PEL Variables ΓòÉΓòÉΓòÉ

Variable  Items

The item descriptions for variables are very similar to those of functions.
The name in the title line of course does not contain parentheses and there is
no return value description.  Let's take a look at our example of an item
description for a variable:

window_text_width   read-only, window

____________

Purpose: Tells how many columns of text a window contains.

____________

Type:   int window_text_width

____________

Description:

Each window has a window_text_width variable associated with it.  The
window_text_width variable indicates how many columns of text can appear in the
window.  Borders are not included in this measurement.  In addition, displaying
line numbers reduces this measure.

The first difference between this example and that of the description of a
function is the additional information contained in the title line at the
extreme right.  This title line indicates that the variable is read-only and is
a "per window" variable.

As you might expect, the read-only status means you can read the value variable
contains but you may not modify that value directly.  The word window at the
far right of the title line says that each window has a value corresponding to
this variable.  Which value you get depends entirely on which window is
current.  Similarly, the word buffer in this position identifies a variable
that changes depending upon which buffer is current.

Another couple of words that occasionally appear in the title line of the item
description are AWK and PEL.  AWK is used to indicate that the variable or
function has been inherited from the AWK programming language.  The PEL word is
used to identify functions and variables that are defined in the extension
language (PEL) source code.

The last difference between the variable and function item descriptions is that
instead of a synopsis of the syntax used by the function there is a type
declaration.  Once again you are reminded that types are never declared in the
editor's extension language.  These type declarations in the manual serve an
informative purpose only.  If you put a similar declaration in your function
source code you will receive an error from the PEL compiler.


ΓòÉΓòÉΓòÉ 15.1. Blocks and Bookmarks ΓòÉΓòÉΓòÉ

_SELECTION
          Constants defining types of selections.
find_mark
          Mark displayed when search pattern is found in ispf.
marks_used
          Stores the number of marks in use by user and system.


ΓòÉΓòÉΓòÉ 15.1.1. _SELECTION ΓòÉΓòÉΓòÉ

_SELECTION

Purpose:  Constants defining types of selections.

____________

Type:    const int _SELECTION

____________

Description: The constants defined in the _SELECTION section are used in
functions like begin_selection() to define the type of selection.

COLUMN_SELECTION
          Selection is confined within column boundaries.
INCLUSIVE_SELECTION
          Selection includes current cursor position.
LINE_SELECTION
          Selection includes only whole lines.
NO_SELECTION
          No selection.
NORMAL_SELECTION
          Normal selection type.

____________


ΓòÉΓòÉΓòÉ 15.1.2. find_mark ΓòÉΓòÉΓòÉ

find_mark   PEL

Purpose:  Mark displayed when search pattern is found in ispf.

____________

Type:    str find_mark

____________

Description: The find_mark variable is shown in the linenumber field when the
search pattern is found on the corresponding line.  This will only be displayed
int the ispf() emulation mode.

____________


ΓòÉΓòÉΓòÉ 15.1.3. marks_used ΓòÉΓòÉΓòÉ

marks_used  read-only   Primitive

Purpose: Stores the number of marks in use by user and system.

____________

Type: int marks_used

____________

Description: This variable stores the number of bookmarks currently in use by
the system, through library functions, and the user for all buffers.

The actual number of bookmarks available to the user is somewhat less, however,
since a number of additional bookmarks may be required by library functions.
When possible, it is best to leave five bookmarks, times the number of buffers
in use, available to library functions.

This value is updated by the system and may not be modified by user functions.

____________

See also:   marks_in_buffer()


ΓòÉΓòÉΓòÉ 15.2. Buffers ΓòÉΓòÉΓòÉ

BUFFER_
          Masks for the buffer_flags variable.
buffer_eof_string
          Tells whether Ctrl-Z character gets special treatment.
buffer_eol_string
          Designates the end-of-line character sequence.
buffer_filename
          Stores the name of the corresponding buffer disk file.
buffer_flags
          Stores a number of buffer attributes as flags.
buffer_last_line
          Stores the number of lines currently in the buffer.
buffer_name
          Provides an identifying label for the current buffer.
buffer_offset
          Tells number of characters preceding current position.
buffer_original_filename
          Stores the name of the file originally read into buffer.
buffer_size
          Tells the size of the buffer contents in characters.
buffer_tabs
          Contains the locations where tab stops are found.
buffers_modified()
          Tells number of edit buffers which have been altered.
current_buffer
          Identifies the currently active edit buffer.
current_column
          Stores the column number of the current position.
current_line
          Stores the line number of the current position.
current_line_length
          Stores the length of the current line in characters.
current_line_offset
          Stores the character offset of the current line position.
current_line_width
          Stores the length of the current line in columns.
default_buffer_eof_string
          Tells whether Ctrl-Z character gets special treatment.
default_buffer_eol_string
          Designates the end-of-line character sequence.
default_buffer_flags
          Stores a number of buffer attributes as flags.
default_buffer_tabs
          Contains the locations where tab stops are found.
default_visible_end_buffer
          Designates string representing the end of buffer.
distance_next_tab
          Indicates the number of columns to next tab stop.
distance_prev_tab
          Indicates the number of columns to previous tab stop.
visible_end_buffer
          Designates string representing the end of buffer.


ΓòÉΓòÉΓòÉ 15.2.1. BUFFER_ ΓòÉΓòÉΓòÉ

BUFFER_   PEL

Purpose: Masks for the buffer_flags variable.

____________

Type: const int BUFFER_

____________

Description: The constants defined in the BUFFER_ section are used as masks to
modify and examine the buffer_flags variable.

o BUFFER_AUTOSAVE_MODIFIED
o BUFFER_CONTROL_Z_IS_EOF
o BUFFER_EXPAND_TABS
o BUFFER_IN_VIRTUAL_SPACE
o BUFFER_MODIFIED
o BUFFER_NO_UNDO
o BUFFER_OVERTYPE_MODE
o BUFFER_POSITION_IS_VIRTUAL
o BUFFER_READ_ONLY
o BUFFER_REAL_SPACE_ONLY
o BUFFER_SCRATCH
o BUFFER_SNAP_TO_EOL
o BUFFER_SYSTEM
o BUFFER_TABS_TO_SPACES
o BUFFER_WHOLE_LINES
o BUFFER_WP_ENABLED
o BUFFER_WP_WRAP_CONTINUOUS

____________


ΓòÉΓòÉΓòÉ 15.2.2. buffer_eof_string ΓòÉΓòÉΓòÉ

buffer_eof_string   Primitive

Purpose: Tells whether Ctrl-Z character gets special treatment.

____________

Type:   str buffer_eof_string

____________

Description:

Each edit buffer has a buffer_eof_string variable associated with it.  This
variable is for use when creating or editing a file which should or already
does use a Ctrl-Z character (1AH) to mark the End-Of-File (EOF).  Alternately,
the EOF is determined by the file size recorded by the operating system.

The permissible settings for this variable are either an empty string or a
string containing only a Ctrl-Z.  When this variable is a Ctrl-Z rather than an
empty string, the associated buffer receives special treatment when the file is
read or written. Examples:   buffer_eof_string = "\x1a"   buffer_eof_string =
chr(0x1a)

When reading, data is read from the file into the buffer only until a Ctrl-Z
character (ASCII decimal value 26) is read. The Ctrl-Z is not placed in the
buffer and the rest of the file is ignored.  When writing the file, the
contents of the buffer are written to disk with a Ctrl-Z character appended to
the end.

When this variable is an empty string the entire file, based on the size
recorded by DOS, is read into the buffer.  No special treatment is given to
Ctrl-Z.

This variable may be modified at any time after the buffer has been created.
However, the associated buffer must be the currently active buffer at the time
it is modified.

Since create_buffer() and therefore edit_file() create the buffer and read in
the file as a single action you cannot affect the reading of the file by
modifying this variable.  To recognize Ctrl-Z in a new buffer the
default_buffer_eof_string must be set accordingly.

The default value for this variable is taken from the default_buffer_eof_string
variable at the time the buffer is created.


ΓòÉΓòÉΓòÉ 15.2.3. buffer_eol_string ΓòÉΓòÉΓòÉ

buffer_eol_string   Primitive

Purpose: Designates the end-of-line character sequence.

____________

Type:   str buffer_eol_string

____________

Description:

Each edit buffer has a buffer_eol_string variable associated with it.  The
value of this variable is set to the value of the default_buffer_eol_string
variable at the time the buffer is created.

The character or characters contained in the buffer_eol_string are used by the
editor as the line termination sequence or end-of- line marker (EOL).  When the
insert_newline() function is called this string is inserted in the text and the
cursor moves to column 0 of the next line. The insert_newline() function is
normally associated with the [Enter] or [Return] key.

The value of buffer_eol_string may not be modified by the user.  You may
influence its value, however, by changing the value of the
default_buffer_eol_string variable. The value of buffer_eol_string is inherited
from this variable at the time the buffer is created.

The end of line string may be any one or two character sequence.  If two
characters are used they may not be the same character.  Typical values for
this variable include:  a carriage return and line feed combination, just a
line feed or just a carriage return.  See the description of the
default_buffer_eol_string variable for a description of this variable's default
value.

____________

See also:  insert_newline(), default_buffer_eol_string


ΓòÉΓòÉΓòÉ 15.2.4. buffer_filename ΓòÉΓòÉΓòÉ

buffer_filename   Primitive

Purpose: Stores the name of the corresponding buffer disk file.

____________

Type:   str buffer_filename

____________

Description:

Each edit buffer has a buffer_filename variable associated with it.  The
variable buffer_filename contains the name of the file, including complete
path, to which the edited buffer is intended to be saved.

When the buffer is created, this variable is set to the value of the
buffer_original_filename variable (input filename).

A user written function that modifies this variable need not supply the entire
path to the filename stored in buffer_filename. the editor will fill in the
missing elements with the default drive and directory, as required.  If this
variable contains an invalid drive or directory, an error is generated when an
attempt is made to save the buffer to disk.

____________

See also:  buffer_original_filename


ΓòÉΓòÉΓòÉ 15.2.5. buffer_flags ΓòÉΓòÉΓòÉ

buffer_flags   Primitive

Purpose: Stores a number of buffer attributes as flags.

____________

Type:   int buffer_flags

____________

Description:

Each buffer has a buffer_flags. variable associated with it.  The least
significant 16 bits of the buffer_flags. variable describe the state of various
attributes of the buffer.  Individual bits of buffer_flags are used by the
editor to signify if the buffer has been modified since the last save, whether
buffer may be modified and so on. The buffer_flags variable takes its initial
value from the default_buffer_flags at the time the buffer is created.

A number of descriptive identifiers have been defined in the standard library
files to facilitate testing and modifying these bits.  These identifiers and
their numeric values are given below.  Those bits which may not be modified by
the user are noted as read-only (r/o):

o BUFFER_SYSTEM
o BUFFER_POSITION_IS_VIRTUAL
o BUFFER_READ_ONLY
o BUFFER_AUTOSAVE_MODIFIED
o BUFFER_MODIFIED
o BUFFER_OVERTYPE_MODE
o BUFFER_EXPAND_TABS
o BUFFER_WP_ENABLED
o BUFFER_SNAP_TO_EOL
o BUFFER_REAL_SPACE_ONLY
o BUFFER_NO_UNDO
o BUFFER_TABS_TO_SPACES
o BUFFER_WHOLE_LINES

When the bit corresponding to each of these attributes is set ( 1 ), that
parameter is turned on.  Otherwise, the attribute is off ( 0 ).

Some of the bits in this list are read-only.  You may consult the setting of
these bits but you may not alter their state after the buffer is created. You
may however control the value of these bits at the time the buffer is created.

See create_buffer() for a description of how this is done.


ΓòÉΓòÉΓòÉ 15.2.5.1. BUFFER_SYSTEM ΓòÉΓòÉΓòÉ

BUFFER_SYSTEM (r/o) (0x0001)

This bit identifies the buffer as having been created for system use.  The
contents of system buffers are not intended for editing and are not normally
meaningful to the user.  This bit may only be modified by the system.


ΓòÉΓòÉΓòÉ 15.2.5.2. BUFFER_POSITION_IS_VIRTUAL ΓòÉΓòÉΓòÉ

BUFFER_POSITION_IS_VIRTUAL (r/o) (0x0002)

Tells the editor that the cursor is currently located in virtual space.


ΓòÉΓòÉΓòÉ 15.2.5.3. BUFFER_READ_ONLY ΓòÉΓòÉΓòÉ

BUFFER_READ_ONLY (0x0010)

This bit tells whether the file originally read into the buffer had a read-only
file attribute.  When the editor detects that the file is read-only, it sets
this bit.  The operating system will prevent the editor from overwriting the
file until the file attribute is changed.  If you change the file attribute
(see filemode()) during editing outside of the editor, you may modify this bit
to reflect that change.


ΓòÉΓòÉΓòÉ 15.2.5.4. BUFFER_AUTOSAVE_MODIFIED ΓòÉΓòÉΓòÉ

BUFFER_AUTOSAVE_MODIFIED (0x0020)

This bit serves a similar purpose to the BUFFER_MODIFIED bit.  The difference
is that BUFFER_AUTOSAVE_MODIFIED is used by the auto-save feature.  Auto-save,
whose use is optional, automatically saves a file to disk after a specified
period of keyboard inactivity.  This bit allows auto-save to determine if the
file has been modified since the last auto-save or normal save operation.


ΓòÉΓòÉΓòÉ 15.2.5.5. BUFFER_MODIFIED ΓòÉΓòÉΓòÉ

BUFFER_MODIFIED (0x0040)

This bit identifies whether or not the buffer has been edited since the last
save.  Resetting this bit to 0 allows exiting without being prompted to save
changes even if the buffer has been modified.


ΓòÉΓòÉΓòÉ 15.2.5.6. BUFFER_OVERTYPE_MODE ΓòÉΓòÉΓòÉ

BUFFER_OVERTYPE_MODE (0x0080)

This bit indicates whether new characters typed are inserted (off) at the
cursor position, or new characters typed overwrite (on) the characters at the
cursor position.  This bit is consulted by the insert_key() and backspace()
functions and determines their effect.


ΓòÉΓòÉΓòÉ 15.2.5.7. BUFFER_EXPAND_TABS ΓòÉΓòÉΓòÉ

BUFFER_EXPAND_TABS (0x0100)

 This bit causes tabs to be converted to spaces when writing the file, when it
is on.  Changing the setting of this bit has no immediate effect, however.


ΓòÉΓòÉΓòÉ 15.2.5.8. BUFFER_WP_ENABLED ΓòÉΓòÉΓòÉ

BUFFER_WP_ENABLED (0x0200)

When the bit is on, word-wrap features are applied to the current paragraph of
the buffer.  As text is added or deleted from the paragraph, the lines of text
are reformatted as necessary to conform to word processing margins (see
wp_left_margin and wp_right_margin).


ΓòÉΓòÉΓòÉ 15.2.5.9. BUFFER_REAL_SPACE_ONLY ΓòÉΓòÉΓòÉ

BUFFER_REAL_SPACE_ONLY (0x0400)

When set, the cursor will not enter virtual space.  If it is off, the cursor
may enter virtual space.


ΓòÉΓòÉΓòÉ 15.2.5.10. BUFFER_SNAP_TO_EOL ΓòÉΓòÉΓòÉ

BUFFER_SNAP_TO_EOL (0x0800)

 When set, characters typed beyond the end of line in virtual space are moved
backward to the end of line.  If the bit is not set, the characters remain
where they are typed.


ΓòÉΓòÉΓòÉ 15.2.5.11. BUFFER_NO_UNDO ΓòÉΓòÉΓòÉ

BUFFER_NO_UNDO (r/o) (0x1000)

When a buffer is created with this bit set, the editor will not maintain a
history of what has been modified in the file.  This means that the undo() and
redo() features will have no effect for this buffer.  Normally this is only
desirable for system buffers and other buffers used for temporary storage.


ΓòÉΓòÉΓòÉ 15.2.5.12. BUFFER_TABS_TO_SPACES ΓòÉΓòÉΓòÉ

BUFFER_TABS_TO_SPACES. (0x2000)

When set, the editor will fill in the appropriate number of real spaces instead
of a tab.


ΓòÉΓòÉΓòÉ 15.2.5.13. BUFFER_WHOLE_LINES ΓòÉΓòÉΓòÉ

BUFFER_WHOLE_LINES (0x4000)

When the set, a newline is appended to the end of the file if not already
present.  This bit is not set by default.


ΓòÉΓòÉΓòÉ 15.2.6. buffer_last_line ΓòÉΓòÉΓòÉ

buffer_last_line   Primitive

Purpose: Stores the number of lines currently in the buffer.

____________

Type:   int buffer_last_line

____________

Description:

The buffer_last_line variable indicates the size of the buffer in lines.  This
variable may be used to move directly to positions relative to the end of the
buffer or to determine when you have reached the end of the buffer.

This count includes the last line of the buffer even if it has not been
terminated with an end-of-line sequence.

When this value is initially calculated for large files, there can be a
noticeable delay.  For this reason the value is not calculated until this
variable is first used or interrogated.  Once the value has been calculated, it
is kept updated and is then available without delay.

____________

See also:  current_line, buffer_size, buffer_offset, goto_buffer_offset()


ΓòÉΓòÉΓòÉ 15.2.7. buffer_name ΓòÉΓòÉΓòÉ

buffer_name   Primitive

Purpose: Provides an identifying label for the current buffer.

____________

Type:   str buffer_name

____________

Description:

Each edit buffer has a buffer_name variable associated with it.  buffer_name is
a string used as a label for the associated buffer.  This label is displayed as
a title on the window viewing the buffer.  It is also possible to search for
buffers with a certain buffer_name, using the next_buffer() and prev_buffer()
functions.

By default, this string is set to the base or root name of the variable
buffer_filename when the buffer is created or when the name of the associated
file is changed.  Changing this string value does not effect the value of
buffer_filename, however.


ΓòÉΓòÉΓòÉ 15.2.8. buffer_offset ΓòÉΓòÉΓòÉ

buffer_offset   Primitive

Purpose: Tells number of characters preceding current position.

____________

Type:   int buffer_offset

____________

Description:

Each edit buffer has a buffer_offset variable associated with it.  The
buffer_offset variable stores the number of characters between the current
position in the buffer and the beginning of the buffer. Tabs count as only one
character in this calculation.

This variable is Read-Only and may not be modified by the user or user written
functions.  The initial value of this variable is zero.

____________

See also:  current_line, buffer_last_line, buffer_size, goto_buffer_offset()


ΓòÉΓòÉΓòÉ 15.2.9. buffer_original_filename ΓòÉΓòÉΓòÉ

buffer_original_filename   Primitive

Purpose: Stores the name of the file originally read into buffer.

____________

Type:   str buffer_original_filename

____________

Description:

Each edit buffer has a buffer_original_filename variable associated with it.
The variable buffer_original_filename contains the name of the file, including
complete path, from which data was first read into the buffer.

The value of this variable is set by the editor system at the time that the
buffer is created and may not later be changed by the user.

____________

See also:  buffer_filename


ΓòÉΓòÉΓòÉ 15.2.10. buffer_size ΓòÉΓòÉΓòÉ

buffer_size   Primitive

Purpose: Tells the size of the buffer contents in characters.

____________

Type:   int buffer_size

____________

Description:

Each edit buffer has a buffer_size variable associated with it.  The
buffer_size variable stores the number of characters currently occupying the
buffer.

Tabs are counted as a single character. The value of buffer_size may vary from
the size of the file on disk if alterations such as tab expansion have been
made.  When the Ctrl-Z character is being treated as the end of file it is not
included in this count.

Unlike the variable buffer_last_line, there is never a delay in calculating
this value regardless of the size of the file.

____________

See also: buffer_eof_string, buffer_offset, goto_buffer_offset(),
buffer_last_line


ΓòÉΓòÉΓòÉ 15.2.11. buffer_tabs ΓòÉΓòÉΓòÉ

buffer_tabs   Primitive

Purpose: Contains the locations where tab stops are found.

____________

Type:   str buffer_tabs

____________

Description:

Each edit buffer has a buffer_tabs variable associated with it.  This string
stores a list of column numbers, in ascending order, at which tab stops are
placed.  The maximum column number which may be specified in this string is
128.  References to higher column numbers will cause the editor to ignore the
buffer_tabs variable and use the previous value instead.

The interval between the last two tab stops on this list is used to define
additional tab stops for columns beyond those listed. For example, if the
buffer_tabs string were as follows:  "5  9" tab stops will be found at every
fourth column regardless of how long the line is.

This variable takes its initial value from the global variable
default_buffer_tabs at the time the buffer is created.


ΓòÉΓòÉΓòÉ 15.2.12. buffers_modified ΓòÉΓòÉΓòÉ

buffers_modified  read-only   Primitive

Purpose: Tells number of edit buffers which have been altered.

____________

Type:   int buffers_modified

____________

Description:

The buffers_modified variable stores the number of buffers containing edits
which have not been saved to disk file.  When this variable has a zero value it
may be considered safe to exit the editor without saving.

This variable may only be modified by the system.


ΓòÉΓòÉΓòÉ 15.2.13. current_buffer ΓòÉΓòÉΓòÉ

current_buffer   Primitive

Purpose: Identifies the currently active edit buffer.

____________

Type:   bufid current_buffer

____________

Description:

The buffer id for the currently active buffer is stored in current_buffer. This
variable may be read, used in comparisons and may be assigned any valid buffer
id.  Care should be taken in making assignments to current_buffer, however,
since changing the current buffer changes the buffer associated with the
current window.

____________

See also:  create_buffer(), delete_buffer(), attach_window_buffer()


ΓòÉΓòÉΓòÉ 15.2.14. current_column ΓòÉΓòÉΓòÉ

current_column buffer   Primitive

Purpose: Stores the column number of the current position.

____________

Type:   int current_column

____________

Description:

Each edit buffer has a current_column variable associated with it.  The column
number of the current position in the active buffer is stored in the variable
current_column.

The column count begins with column 1, which is the first column represented at
the far left of the edit window before scrolling.  This is not a screen
coordinate but rather a buffer location.

When this value is modified by the user, the cursor moves to the column
indicated by the new value.

____________

See also:  current_line


ΓòÉΓòÉΓòÉ 15.2.15. current_line ΓòÉΓòÉΓòÉ

current_line   Primitive

Purpose: Stores the line number of the current position.

____________

Type: int current_line

____________

Description:

Each edit buffer has a current_line variable associated with it.  The line
number of the current position in the active buffer is stored in the variable
current_line.

The line count begins with line 1, which is the first line of the buffer.  This
is not a screen coordinate but rather a buffer location.

When this value is modified by the user, the cursor moves to the line indicated
by the new value.  Negative values assigned to current_line will be treated as
1.

See also:  current_column


ΓòÉΓòÉΓòÉ 15.2.16. current_line_length ΓòÉΓòÉΓòÉ

current_line_length   Primitive

Purpose: Stores the length of the current line in characters.

____________

Type: int current_line_length

____________

Description:

The current_line_length variable stores the number of characters in the current
line. In this count tabs count only as a single character.  The number of
columns occupied by the line will depend upon how many tabs the line contains.

____________

See also:  current_line_width


ΓòÉΓòÉΓòÉ 15.2.17. current_line_offset ΓòÉΓòÉΓòÉ

current_line_offset   Primitive

Purpose: Stores the character offset of the current line position.

____________

Type: current_line_offset

____________

Description:

Each edit buffer has a current_line_offset variable associated with it.  The
number of characters preceding the current position in the line is stored in
the variable current_line_offset.  When the cursor is in column one this value
will therefore be zero.

This value may not be modified by the user or user written functions.  The
variable current_column may be used to change the position in the line.

____________

See also:  current_column


ΓòÉΓòÉΓòÉ 15.2.18. current_line_width ΓòÉΓòÉΓòÉ

current_line_width   Primitive

Purpose: Stores the length of the current line in columns.

____________

Type: int current_line_width

____________

Description:

The current_line_width variable stores the number of columns the current line
occupies, based on current settings.  This is not a count of characters in the
current line.  The number of characters in the line will depend upon how many
columns are occupied by tabs.

____________

See also:  current_line_length


ΓòÉΓòÉΓòÉ 15.2.19. default_buffer_eof_string ΓòÉΓòÉΓòÉ

default_buffer_eof_string   Primitive

Purpose: Tells whether Ctrl-Z character gets special treatment.

____________

Type:   str default_buffer_eof_string

____________

Description:

The default_buffer_eof_string variable contains the initial value of the
buffer_eof_string variable when a new buffer is created.

____________

See also:  buffer_eof_string


ΓòÉΓòÉΓòÉ 15.2.20. default_buffer_eol_string ΓòÉΓòÉΓòÉ

default_buffer_eol_string   Primitive

Purpose: Designates the end-of-line character sequence.

____________

Type:   str default_buffer_eol_string

____________

Description:

The default_buffer_eol_string variable contains the initial value of the
buffer_eol_string variable when a new buffer is created.

____________

See also:  buffer_eol_string


ΓòÉΓòÉΓòÉ 15.2.21. default_buffer_flags ΓòÉΓòÉΓòÉ

default_buffer_flags   Primitive

Purpose: Stores a number of buffer attributes as flags.

____________

Type:   int default_buffer_flags

____________

Description:

The default_buffer_flags variable contains the initial value of the
buffer_flags variable when a new buffer created.

____________

See also:  buffer_flags


ΓòÉΓòÉΓòÉ 15.2.22. default_buffer_tabs ΓòÉΓòÉΓòÉ

default_buffer_tabs   Primitive

Purpose: Contains the locations where tab stops are found.

____________

Type:   str default_buffer_tabs

____________

Description:

The default_buffer_tabs variable contains the initial value of the buffer_tabs
variable when a new buffer is created.

____________

See also:  buffer_tabs


ΓòÉΓòÉΓòÉ 15.2.23. default_visible_end_buffer ΓòÉΓòÉΓòÉ

default_visible_end_buffer   Primitive

Purpose: Designates string representing the end of buffer.

____________

Type:   str default_visible_end_buffer

____________

Description:

The default_visible_end_buffer variable contains the initial value of the
visible_end_buffer variable when a new buffer is created.

____________

See also:  visible_end_buffer


ΓòÉΓòÉΓòÉ 15.2.24. distance_next_tab ΓòÉΓòÉΓòÉ

distance_next_tab read-only   Primitive

Purpose: Indicates the number of columns to next tab stop.

____________

Type:   int distance_next_tab

____________

Description:

Each edit buffer has a distance_next_tab variable associated with it.  The
number stored in distance_next_tab represents the column number of the current
position subtracted from the column number of the tab stop to the right.  This
gives the number of columns which must be transited to reach the next tab stop.

This value is updated by the system and may not be modified by the user.

____________

See also:  distance_prev_tab


ΓòÉΓòÉΓòÉ 15.2.25. distance_prev_tab ΓòÉΓòÉΓòÉ

distance_prev_tab  read-only   Primitive

Purpose: Indicates the number of columns to previous tab stop.

____________

Type:   int distance_prev_tab

____________

Description:

Each edit buffer has a distance_prev_tab variable associated with it.  The
number stored in distance_prev_tab represents the column number of the tab stop
to the left subtracted from the column number of the current position.  This
gives the number of columns which must be transited to reach the previous tab
stop.

This value is updated by the system and may not be modified by the user.

____________

See also:  distance_next_tab


ΓòÉΓòÉΓòÉ 15.2.26. visible_end_buffer ΓòÉΓòÉΓòÉ

visible_end_buffer   Primitive

Purpose: Designates string representing the end of buffer.

____________

Type: str visible_end_buffer

____________

Description: Each window has a visible_end_buffer variable associated with it.
The visible_end_buffer variable is a string to be displayed demonstrating the
location of the end of the buffer.  This string is not saved in the file, but
only appears on screen.

Usually this string is a single character such as "\x04", which is a diamond.
This variable takes its initial value from the global variable
default_visible_end_buffer at the time the buffer is created.

____________

See also:   visible_newlines,visible_spaces, visible_tabs,
visible_virtual_lines, visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.3. Dialog Windows ΓòÉΓòÉΓòÉ

DAC_
          Dialog action codes.
DCTRL_
          Constants defining dialog controls.
DM_
          Constants for messages from dialog boxes.
DRC_
          Constants used as callback function return values.
DWC_
          Constants for dialog windows.
callback_data
          Contains information useful for processing in dialog callbacks.
callback_dialog_handle
          Contains the id of the dialog box which generated the last callback
          message.
callback_index
          Contains the id of the dialog box item which generated the last
          callback message.
callback_msg
          Contains the id of the event that caused the dialog callback to be
          called.


ΓòÉΓòÉΓòÉ 15.3.1. DCTRL_ ΓòÉΓòÉΓòÉ

DCTRL_   Primitive

Purpose:  Constants defining dialog controls.

____________

Type:    const int DCTRL_

____________

Description: The constants defined in the DCTRL_ section are used as parameters
to the add_dialog_item().  They are easy to read names for the dialog controls.

o DCTRL_CHECK_BOX
o DCTRL_COMBO_BOX
o DCTRL_DEFAULT_PUSH_BUTTON
o DCTRL_EDIT
o DCTRL_EDIT_KEY
o DCTRL_GROUP_BOX
o DCTRL_LIST_BOX
o DCTRL_MLE
o DCTRL_MLE_KEY
o DCTRL_MULTI_LIST_BOX
o DCTRL_NOTEBOOK
o DCTRL_PUSH_BUTTON
o DCTRL_RADIO_BUTTON
o DCTRL_SPINBUTTON
o DCTRL_STATIC_TEXT
o DCTRL_TRISTATE
o DCTRL_VALUESET

____________


ΓòÉΓòÉΓòÉ 15.3.2. DM_ ΓòÉΓòÉΓòÉ

DM_   Primitive

Purpose:  Constants for messages from dialog boxes.

____________

Type:    const int DM_

____________

Description: The constants defined in the DM_ section are the messages received
from dialog boxes.

o DM_ACTIVATE
o DM_CANCEL
o DM_CHANGE
o DM_CLICK
o DM_CLOSE
o DM_DEACTIVATE
o DM_DOUBLE_CLICK
o DM_DROP_DOWN
o DM_HELPREQUESTED
o DM_INIT
o DM_INVALID_PCHAR
o DM_KEY
o DM_KILL_FOCUS
o DM_MENUCOMMAND
o DM_MENUSELECT
o DM_OK
o DM_PAGECHANGED
o DM_RESIZE
o DM_SELECT
o DM_SPIN_CHANGE
o DM_SPIN_DOWN
o DM_SPIN_END
o DM_SPIN_UP
o DM_SET_FOCUS
o DM_VS_ENTER
o DM_VS_HELP
o DM_VS_SELECT

____________


ΓòÉΓòÉΓòÉ 15.3.3. DRC_ ΓòÉΓòÉΓòÉ

DRC_   Primitive

Purpose:  Constants used as callback function return values.

____________

Type:    const int DRC_

____________

Description: The constants defined in the DRC_ section are messages used as
return values from dialog callbacks.

DRC_CONTINUE
          Passes the unprocessed message back to the operating system.
DRC_EXIT
          Exits the dialog.
DRC_MSG_PROCESSED
          Indicates that the message has been processed.

____________


ΓòÉΓòÉΓòÉ 15.3.4. DWC_ ΓòÉΓòÉΓòÉ

DWC_   Primitive

Purpose:  Constants for dialog windows.

____________

Type:    const int DWC_

____________

Description: The constants in the DWC_ section are for use in functions like
set_dialog_window().  They are the dialog window controls.

o DWC_HIDE
o DWC_NORMALBORDER
o DWC_POSITION
o DWC_SHOW
o DWC_SIZE
o DWC_SIZEBORDER
o DWC_STATUSBAR
o DWC_STATUSBARSIZE
o DWC_STATUSBARTEXT
o DWC_STICKONTOP
o DWC_SYS_MENU
o DWC_TITLE
o DWC_TO_TOP

____________


ΓòÉΓòÉΓòÉ 15.3.5. callback_data ΓòÉΓòÉΓòÉ

callback_data   Primitive

Purpose: Contains information useful for processing in dialog callbacks.

____________

Type:   any callback_data

____________

Description:

The callback_data handle contains data that is used when processing dialog box
messages.  The information contained in callback_data is specific to each
message generated by the dialog box manager.  The value of callback_data is
valid only for the duration of the current callback function.  This variable is
overwritten every time a dialog box callback message is generated.

____________

See also:  callback_dialog_handle, callback_index, callback_msg


ΓòÉΓòÉΓòÉ 15.3.6. callback_dialog_handle ΓòÉΓòÉΓòÉ

callback_dialog_handle   Primitive

Purpose: Contains the id of the dialog box which generated the last callback
message.

____________

Type:   int callback_dialog_handle

____________

Description:

The callback_dialog_handle contains the id of the dialog box that resulted in
the callback function being called.  The value of callback_dialog_handle is
valid only for the duration of the current callback function.  This variable is
overwritten every time a dialog box callback message is generated.

____________

See also:  callback_data, callback_index, callback_msg


ΓòÉΓòÉΓòÉ 15.3.7. callback_index ΓòÉΓòÉΓòÉ

callback_index   Primitive

Purpose: Contains the id of the dialog box item which generated the last
callback message.

____________

Type:   int callback_index

____________

Description:

The callback_index variable contains the id of the dialog box control that
resulted in the callback function being called.  The value of callback_index is
valid only for the duration of the current callback function.  This variable is
overwritten every time a dialog box callback message is generated.

____________

See also:  callback_dialog_handle, callback_index, callback_msg


ΓòÉΓòÉΓòÉ 15.3.8. callback_msg ΓòÉΓòÉΓòÉ

callback_msg   Primitive

Purpose: Contains the id of the event that caused the dialog callback to be
called.

____________

Type:   int callback_msg

____________

Description:

The callback_msg variable contains the message id that resulted in the callback
function being called.  The value of callback_msg is valid only for the
duration of the current callback function.  This variable is overwritten every
time a dialog box callback message is generated.

See the DM_ section for a list of possible messages that are sent to a user
dialog callback function.

____________

See also:  callback_dialog_handle, callback_index, callback_msg


ΓòÉΓòÉΓòÉ 15.3.9. DAC_ ΓòÉΓòÉΓòÉ

DAC_   Primitive

Purpose: Dialog action codes.

____________

The following table lists all the valid dialog action codes(DAC) generated by
the dialog manager.

o DAC_ADD_INDEX
o DAC_ADD_ITEM
o DAC_APPEND_PAGE
o DAC_BG_COLOR
o DAC_CHECK
o DAC_CLEAR
o DAC_CLEAR_LIST
o DAC_COPY
o DAC_COUNT_ITEMS
o DAC_COUNT_LINES
o DAC_COUNT_SELECTED
o DAC_CUT
o DAC_DELETE_INDEX
o DAC_DELETE_ITEM
o DAC_DESELECT_INDEX
o DAC_DESELECT_INDEX_RANGE
o DAC_DESELECT_ITEMADDINDEX
o DAC_DISABLE
o DAC_EDIT_KEY_TEXT
o DAC_EDIT_TEXT
o DAC_ENABLE
o DAC_FG_COLOR
o DAC_FIND
o DAC_FIRST_INDEX
o DAC_FIRST_ITEM
o DAC_FONT
o DAC_GET_INDEX_ITEM
o DAC_GET_LINE
o DAC_GRAY_CHECK
o DAC_HIDE
o DAC_INSERT_PAGE_AFTER
o DAC_INSERT_PAGE_AT_TOP
o DAC_INSERT_PAGE_BEFORE
o DAC_LINEDOWN
o DAC_LINEUP
o DAC_MODIFIED
o DAC_NEXT_INDEX
o DAC_NEXT_ITEM
o DAC_NO_SORT
o DAC_PAGEDOWN
o DAC_PAGEUP
o DAC_PASTE
o DAC_POSITION
o DAC_SCROLL_HORIZ
o DAC_SCROLL_VERT
o DAC_SELECTED_RANGE
o DAC_SELECTED_TEXT
o DAC_SELECTION
o DAC_SELECT_INDEX
o DAC_SELECT_INDEX_RANGE
o DAC_SELECT_ITEM
o DAC_SETFOCUS
o DAC_SET_BACKPAGES
o DAC_SET_BINDER_TYPE
o DAC_SET_BUTTON_SIZE
o DAC_SET_MAJOR_TAB_SIZE
o DAC_SET_MINOR_TAB_SIZE
o DAC_SET_STATUS_ALIGN
o DAC_SET_TAB_ALIGN
o DAC_SET_TAB_LOCATION
o DAC_SET_TAB_TYPE
o DAC_SET_TEXT_LEN
o DAC_SHOW
o DAC_SIZE
o DAC_SORT_ASCENDING
o DAC_SORT_DESCENDING
o DAC_SPIN_DOWN
o DAC_SPIN_LIMITS
o DAC_SPIN_OVERRIDELIMITS
o DAC_SPIN_TEXTLIMIT
o DAC_SPIN_UP
o DAC_SPIN_VALUE
o DAC_TEXT
o DAC_UNCHECK
o DAC_UNDO
o DAC_UNSELECT_ITEM
o DAC_VS_QUERY_ITEM
o DAC_VS_QUERY_METRICS
o DAC_VS_QUERY_SELECTED
o DAC_VS_SELECT_ITEM
o DAC_VS_SET_ITEM
o DAC_VS_SET_METRICS


ΓòÉΓòÉΓòÉ 15.3.9.1. DAC_ADD_INDEX ΓòÉΓòÉΓòÉ

DAC_ADD_INDEX

The DAC_ADD_INDEX flag adds a new item to a list box at the specified offset
from the begining of the list.  The offset is a 0 based value that would add an
item to the top of the list if a 0 index is specified.

The following example adds an element to a list box before the 6th item in the
list.
   set_dialog_item( dlgid, listbox_index, DAC_ADD_INDEX, "New Item", 5 );


ΓòÉΓòÉΓòÉ 15.3.9.2. DAC_ADD_ITEM ΓòÉΓòÉΓòÉ

DAC_ADD_ITEM

The DAC_ADD_ITEM flag adds an item to the end of a list box or combo box.

The following example adds "New Item" to the end of a list box:
   set_dialog_item(dlgid, listbox_index, DAC_ADD_ITEM, "New Item")


ΓòÉΓòÉΓòÉ 15.3.9.3. DAC_APPEND_PAGE ΓòÉΓòÉΓòÉ

DAC_APPEND_PAGE

The DAC_APPEND_PAGE flag appends a page to a notebook control. The
DAC_APPEND_PAGE flag takes one required parameter and five optional parameters.

Parameters:

o Parameter 1(required): Page id returned from the create_page() function.
o Parameter 2(optional): Text to be displayed on the status line.
o Parameter 3(optional): Text to be displayed on the for the page.
o Parameter 4(optional): Type of tab.  See DAC_SET_TAB_TYPE.
o Parameter 5(optional): Display status text (TRUE) or not (FALSE)
o Parameter 6(optional): Auto page size on (TRUE) or off (FALSE). Resizes the
  notebook page whenever the notebook control is resized.

The following example appends a page to an existing notebook control. The page
is created with a status line with the text "Status line text" initially
displayed on the status line.  The tab is displayed as a major tab with the
text "Tab Text".
   set_dialog_item(dlgid, notebook_index, DAC_APPEND_PAGE,            page_id,
"Status line text",            "Tab Text", NBTAB_MAJOR, TRUE)

The next example simply creates a default page with no status bar and no major
or minor tab.
   set_dialog_item(dlgid, notebook_index, DAC_APPEND_PAGE, page_id)


ΓòÉΓòÉΓòÉ 15.3.9.4. DAC_CHECK ΓòÉΓòÉΓòÉ

DAC_CHECK

The DAC_CHECK flag sets a check mark on a tristate, checkbox, or radio button.

Example:
   set_dialog_item(dlgid, control_index, DAC_CHECK)


ΓòÉΓòÉΓòÉ 15.3.9.5. DAC_CLEAR ΓòÉΓòÉΓòÉ

DAC_CLEAR

Example:
   set_dialog_item(dlgd, control_index, DAC_CLEAR)


ΓòÉΓòÉΓòÉ 15.3.9.6. DAC_CLEAR_LIST ΓòÉΓòÉΓòÉ

DAC_CLEAR_LIST

The DAC_CLEAR_LIST flag clears all items from a listbox.

Example:
   set_dialog_item(dlgd, listbox_index, DAC_CLEAR_LIST)


ΓòÉΓòÉΓòÉ 15.3.9.7. DAC_COPY ΓòÉΓòÉΓòÉ

DAC_COPY

Example:
   set_dialog_item(dlgd, control_index, DAC_COPY)


ΓòÉΓòÉΓòÉ 15.3.9.8. DAC_COUNT_ITEMS ΓòÉΓòÉΓòÉ

DAC_COUNT_ITEMS

Example:
   set_dialog_item(dlgd, control_index, DAC_COUNT_ITEMS)


ΓòÉΓòÉΓòÉ 15.3.9.9. DAC_COUNT_LINES ΓòÉΓòÉΓòÉ

DAC_COUNT_LINES

Example:
   set_dialog_item(dlgd, control_index, DAC_COUNT_LINES)


ΓòÉΓòÉΓòÉ 15.3.9.10. DAC_COUNT_SELECTED ΓòÉΓòÉΓòÉ

DAC_COUNT_SELECTED

Example:
   set_dialog_item(dlgd, control_index, DAC_COUNT_SELECTED)


ΓòÉΓòÉΓòÉ 15.3.9.11. DAC_CUT ΓòÉΓòÉΓòÉ

DAC_CUT

Example:
   set_dialog_item(dlgd, control_index, DAC_CUT)


ΓòÉΓòÉΓòÉ 15.3.9.12. DAC_DELETE_INDEX ΓòÉΓòÉΓòÉ

DAC_DELETE_INDEX

The DAC_DELETE_INDEX flag removes an item from a list box at the specified
offset from the begining of the list.  If no value for the index parameter is
specified the entire list box is cleared.  The index specified is a 0 based
index.

The following example removes the 6th element from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_DELETE_INDEX, 5)

The following example removes all elements from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_DELETE_INDEX)


ΓòÉΓòÉΓòÉ 15.3.9.13. DAC_DELETE_ITEM ΓòÉΓòÉΓòÉ

DAC_DELETE_ITEM

The DAC_DELETE_ITEM flag removes a given string or all the items from a list
box or combo box.

The following example removes "New Item" from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_DELETE_ITEM, "New Item")

The following example removes all items from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_DELETE_ITEM)


ΓòÉΓòÉΓòÉ 15.3.9.14. DAC_DESELECT_ITEM ΓòÉΓòÉΓòÉ

DAC_DESELECT_ITEM

The DAC_DESELECT_ITEM flag removes the selection emphasis from an item in a
multiple or single select list box.

The following example removes the selection from a single select list box (this
will also remove all selections from a multiple select list box):
   set_dialog_item(dlgid, listbox_index, DAC_DESELECT_ITEM)

The following example removes the selection emphasis from the multiple select
list box item "New Item":
   set_dialog_item(dlgid, listbox_index, DAC_DESELECT_ITEM, "New Item")


ΓòÉΓòÉΓòÉ 15.3.9.15. DAC_DESELECT_INDEX ΓòÉΓòÉΓòÉ

DAC_DESELECT_INDEX

The DAC_DESELECT_INDEX flag removes the selection emphasis of a list box item
given a zero based index.

The following example removes the selection from a single select list box (this
will also remove all selections from a multiple select list box):
   set_dialog_item(dlgid, listbox_index, DAC_DESELECT_INDEX)

The following example removes the selection emphasis from the 6th item in a
multiple select list box:
   set_dialog_item(dlgid, listbox_index, DAC_DESELECT_INDEX, 5)


ΓòÉΓòÉΓòÉ 15.3.9.16. DAC_EDIT_KEY_TEXT ΓòÉΓòÉΓòÉ

DAC_EDIT_KEY_TEXT

Example:
   set_dialog_item(dlgd, control_index, DAC_EDIT_KEY_TEXT)


ΓòÉΓòÉΓòÉ 15.3.9.17. DAC_EDIT_TEXT ΓòÉΓòÉΓòÉ

DAC_EDIT_TEXT

Example:
   set_dialog_item(dlgd, control_index, DAC_EDIT_TEXT)


ΓòÉΓòÉΓòÉ 15.3.9.18. DAC_FIND ΓòÉΓòÉΓòÉ

DAC_FIND

Example:
   set_dialog_item(dlgd, control_index, DAC_FIND)


ΓòÉΓòÉΓòÉ 15.3.9.19. DAC_FIRST_INDEX ΓòÉΓòÉΓòÉ

DAC_FIRST_INDEX

Example:
   set_dialog_item(dlgd, control_index, DAC_FIRST_INDEX)


ΓòÉΓòÉΓòÉ 15.3.9.20. DAC_FIRST_ITEM ΓòÉΓòÉΓòÉ

DAC_FIRST_ITEM

Example:
   set_dialog_item(dlgd, control_index, DAC_FIRST_ITEM)


ΓòÉΓòÉΓòÉ 15.3.9.21. DAC_FONT ΓòÉΓòÉΓòÉ

DAC_FONT

Example:
   set_dialog_item(dlgd, control_index, DAC_FONT)


ΓòÉΓòÉΓòÉ 15.3.9.22. DAC_GET_INDEX_ITEM ΓòÉΓòÉΓòÉ

DAC_GET_INDEX_ITEM

Example:
   set_dialog_item(dlgd, control_index, DAC_GET_INDEX_ITEM)


ΓòÉΓòÉΓòÉ 15.3.9.23. DAC_GET_LINE ΓòÉΓòÉΓòÉ

DAC_GET_LINE

Example:
   set_dialog_item(dlgd, control_index, DAC_GET_LINE)


ΓòÉΓòÉΓòÉ 15.3.9.24. DAC_GRAY_CHECK ΓòÉΓòÉΓòÉ

DAC_GRAY_CHECK

The DAC_GRAY_CHECK flag grays a tristate, checkbox, or radio button.

Example:
   set_dialog_item(dlgid, control_index, DAC_GRAY_CHECK)


ΓòÉΓòÉΓòÉ 15.3.9.25. DAC_LINEDOWN ΓòÉΓòÉΓòÉ

DAC_LINEDOWN

Example:
   set_dialog_item(dlgd, control_index, DAC_LINEDOWN)


ΓòÉΓòÉΓòÉ 15.3.9.26. DAC_LINEUP ΓòÉΓòÉΓòÉ

DAC_LINEUP

Example:
   set_dialog_item(dlgd, control_index, DAC_LINEUP)


ΓòÉΓòÉΓòÉ 15.3.9.27. DAC_MODIFIED ΓòÉΓòÉΓòÉ

DAC_MODIFIED

Example:
   set_dialog_item(dlgd, control_index, DAC_MODIFIED)


ΓòÉΓòÉΓòÉ 15.3.9.28. DAC_NEXT_INDEX ΓòÉΓòÉΓòÉ

DAC_NEXT_INDEX

Example:
   set_dialog_item(dlgd, control_index, DAC_NEXT_INDEX)


ΓòÉΓòÉΓòÉ 15.3.9.29. DAC_NEXT_ITEM ΓòÉΓòÉΓòÉ

DAC_NEXT_ITEM

Example:
   set_dialog_item(dlgd, control_index, DAC_NEXT_ITEM)


ΓòÉΓòÉΓòÉ 15.3.9.30. DAC_NO_SORT ΓòÉΓòÉΓòÉ

DAC_NO_SORT

The DAC_NO_SORT flag indicates that items added to a list box are not sorted.

The following example sets the no sort flag for the list box:
   set_dialog_item(dlgid, listbox_index, DAC_SORT_DESCENDING)


ΓòÉΓòÉΓòÉ 15.3.9.31. DAC_PAGEDOWN ΓòÉΓòÉΓòÉ

DAC_PAGEDOWN

Example:
   set_dialog_item(dlgd, control_index, DAC_PAGEDOWN)


ΓòÉΓòÉΓòÉ 15.3.9.32. DAC_PAGEUP ΓòÉΓòÉΓòÉ

DAC_PAGEUP

Example:
   set_dialog_item(dlgd, control_index, DAC_PAGEUP)


ΓòÉΓòÉΓòÉ 15.3.9.33. DAC_PASTE ΓòÉΓòÉΓòÉ

DAC_PASTE

Example:
   set_dialog_item(dlgd, control_index, DAC_PASTE)


ΓòÉΓòÉΓòÉ 15.3.9.34. DAC_SCROLL_HORIZ ΓòÉΓòÉΓòÉ

DAC_SCROLL_HORIZ

Example:
   set_dialog_item(dlgd, control_index, DAC_SCROLL_HORIZ)


ΓòÉΓòÉΓòÉ 15.3.9.35. DAC_SCROLL_VERT ΓòÉΓòÉΓòÉ

DAC_SCROLL_VERT

Example:
   set_dialog_item(dlgd, control_index, DAC_SCROLL_VERT)


ΓòÉΓòÉΓòÉ 15.3.9.36. DAC_SELECT_INDEX ΓòÉΓòÉΓòÉ

DAC_SELECT_INDEX

The DAC_SELECT_INDEX flag selects an item from a list box given an index into
the list.  The index specified is a 0 based index, so if 0 where specified as
the index the first item in the list will be selected.

The following example attempts to select the 6th element from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_SELECT_INDEX, 5)


ΓòÉΓòÉΓòÉ 15.3.9.37. DAC_SELECT_ITEM ΓòÉΓòÉΓòÉ

DAC_SELECT_ITEM

The DAC_SELECT_ITEM flag selects an item from a list box.  This action returns
TRUE if the selection was changed otherwise it returns FALSE.

The following example attempts to select the "New Item" string exactly as
entered from a list box:
   set_dialog_item(dlgid, listbox_index, DAC_SELECT_ITEM, "New Item", TRUE)

The following example selects any string from the list box that contains the
substring "New Item" text string:
   set_dialog_item(dlgid, listbox_index, DAC_SELECT_ITEM, "New Item", FALSE)


ΓòÉΓòÉΓòÉ 15.3.9.38. DAC_SELECTED_RANGE ΓòÉΓòÉΓòÉ

DAC_SELECTED_RANGE

Example:
   set_dialog_item(dlgd, control_index, DAC_SELECTED_RANGE)


ΓòÉΓòÉΓòÉ 15.3.9.39. DAC_SELECTED_TEXT ΓòÉΓòÉΓòÉ

DAC_SELECTED_TEXT

Example:
   set_dialog_item(dlgd, control_index, DAC_SELECTED_TEXT)


ΓòÉΓòÉΓòÉ 15.3.9.40. DAC_SELECTION ΓòÉΓòÉΓòÉ

DAC_SELECTION

Example:
   set_dialog_item(dlgd, control_index, DAC_SELECTION)


ΓòÉΓòÉΓòÉ 15.3.9.41. DAC_SET_BACKPAGES ΓòÉΓòÉΓòÉ

DAC_SET_BACKPAGES

The DAC_SET_STATUS_ALIGN flag sets the location of the backpages on the
notebook. Backpages are where the recessed edges of the notebook intersect.
notebook       sets where back pages are shown

The following values are used for setting the back page intersection:

o 0 - BottomRight
o 1 - BottomLeft
o 2 - TopRight
o 3 - TopLeft

The following example sets the back pages intersection to the top right:
   set_dialog_item(dlgid, notebook_index, DAC_SET_BACKPAGES, 2 )


ΓòÉΓòÉΓòÉ 15.3.9.42. DAC_SET_BINDER_TYPE ΓòÉΓòÉΓòÉ

DAC_SET_BINDER_TYPE

The DAC_SET_BINDER_TYPE flag sets the type of binder the notebook control will
display. The binder type can be either solid or spiral.

The following example sets a spiral binder type for a notebook control:
   set_dialog_item(dlgid, notebook_index, DAC_SET_BINDER_TYPE, 1)

The following example sets a solid binder type for a notebook control:
   set_dialog_item(dlgid, notebook_index, DAC_SET_BINDER_TYPE, 0)


ΓòÉΓòÉΓòÉ 15.3.9.43. DAC_SET_BUTTON_SIZE ΓòÉΓòÉΓòÉ

DAC_SET_BUTTON_SIZE

The DAC_SET_BUTTON_SIZE flag sets the width and height in pixels of the arrow
buttons displayed on a notebook control.

The following example sets the width of the arrow buttons to 32 pixels and the
height to 40 pixels for the particular notebook control displayed in a dialog
box:
   set_dialog_item(dlgid, notebook_index, DAC_SET_BUTTON_SIZE, 32, 40)


ΓòÉΓòÉΓòÉ 15.3.9.44. DAC_SET_MAJOR_TAB_SIZE ΓòÉΓòÉΓòÉ

DAC_SET_MAJOR_TAB_SIZE

The DAC_SET_MAJOR_TAB_SIZE flag sets the width and height in pixels of the
major tabs displayed on a notebook control.

The following example sets the width of the major tabs to 50 pixels and the
height to 30 pixels for the particular notebook control displayed in a dialog
box:
   set_dialog_item(dlgid, notebook_index, DAC_SET_MAJOR_TAB_SIZE, 50, 30)


ΓòÉΓòÉΓòÉ 15.3.9.45. DAC_SET_MINOR_TAB_SIZE ΓòÉΓòÉΓòÉ

The DAC_SET_MINOR_TAB_SIZE sets the width and height in pixels of the minor
tabs displayed on a notebook control.

The following example sets the width of the minor tabs to 150 pixels and the
height to 30 pixels for the particular notebook control displayed in a dialog
box:
   set_dialog_item(dlgid, notebook_index, DAC_SET_MINOR_TAB_SIZE, 150, 30)


ΓòÉΓòÉΓòÉ 15.3.9.46. DAC_SET_STATUS_ALIGN ΓòÉΓòÉΓòÉ

DAC_SET_STATUS_ALIGN

The DAC_SET_STATUS_ALIGN flag sets the alignment of the status line displayed
on a notebook control.

The following values are used for setting the status line alignment:

o 0 - left
o 1 - center
o 2 - right

The following example sets the status line alignment to center:
   set_dialog_item(dlgid, notebook_index, DAC_SET_STATUS_ALIGN, 1 )


ΓòÉΓòÉΓòÉ 15.3.9.47. DAC_SET_TAB_ALIGN ΓòÉΓòÉΓòÉ

DAC_SET_TAB_ALIGN

The DAC_SET_TAB_ALIGN flag sets the alignment of text within the tabs displayed
on the notebook control.

The following values are used for setting the tabs text alignment:

o 0 - left
o 1 - center
o 2 - right

The following example sets the text alignment to center of the tabs:
   set_dialog_item(dlgid, notebook_index, DAC_SET_TAB_ALIGN, 1 )


ΓòÉΓòÉΓòÉ 15.3.9.48. DAC_SET_TAB_LOCATION ΓòÉΓòÉΓòÉ

DAC_SET_TAB_LOCATION

The DAC_SET_TAB_LOCATION flag sets the position of major tabs on the notebook
control. The minor tabs are displayed at a position relative to where the major
tabs are displayed.

The following values are used for setting the major tab locations:

o 0 - left
o 1 - right
o 2 - top
o 3 - bottom

The following example sets the position of the major tabs to the left of the
notebook:
   set_dialog_item(dlgid, notebook_index, DAC_SET_TAB_LOCATION, 0 )


ΓòÉΓòÉΓòÉ 15.3.9.49. DAC_SET_TAB_TYPE ΓòÉΓòÉΓòÉ

DAC_SET_TAB_TYPE

The DAC_SET_TAB_TYPE flag sets the shape of major and minor tabs displayed for
a notebook control.  Tabs can be either square, rounded, or polygon.

The following example sets the shape of tabs to square for a notebook control:
   set_dialog_item(dlgid, notebook_index, DAC_SET_TAB_TYPE, 0)

The following example sets the shape of tabs to rounded for a notebook control:
   set_dialog_item(dlgid, notebook_index, DAC_SET_TAB_TYPE, 1)

The following example sets the shape of tabs to polygon for a notebook control:
   set_dialog_item(dlgid, notebook_index, DAC_SET_TAB_TYPE, 2)


ΓòÉΓòÉΓòÉ 15.3.9.50. DAC_SET_TEXT_LEN ΓòÉΓòÉΓòÉ

DAC_SET_TEXT_LEN

The DAC_SET_TEXT flag sets the maximum size of text entered into an edit
control.

The following example sets the maximum number of characters allowed in the edit
field to 20:
   set_dialog_item(dlgid, control_index, DAC_SET_TEXT_LEN, 20)


ΓòÉΓòÉΓòÉ 15.3.9.51. DAC_SORT_ASCENDING ΓòÉΓòÉΓòÉ

DAC_SORT_ASCENDING

The DAC_SORT_ASCENDING flag indicates that items added to a list box are sorted
in ascending order.

The following example sets the ascending sort flag for the list box:
   set_dialog_item(dlgid, listbox_index, DAC_SORT_ASCENDING)


ΓòÉΓòÉΓòÉ 15.3.9.52. DAC_SORT_DESCENDING ΓòÉΓòÉΓòÉ

DAC_SORT_DESCENDING

The DAC_SORT_DESCENDING flag indicates that items added to a list box are
sorted in descending order.

The following example sets the descending sort flag for the list box:
   set_dialog_item(dlgid, listbox_index, DAC_SORT_DESCENDING)


ΓòÉΓòÉΓòÉ 15.3.9.53. DAC_SPIN_DOWN ΓòÉΓòÉΓòÉ

DAC_SPIN_DOWN

This message causes the spin control to show the previous value.

Parameters: A long data value that determines how many units to spin backwards.


ΓòÉΓòÉΓòÉ 15.3.9.54. DAC_SPIN_LIMITS ΓòÉΓòÉΓòÉ

DAC_SPIN_LIMITS

This message causes the spin control to set or reset numeric limits.  The
current value of the spin control is set to the nearest limit if it is out of
the range of the new limits.

Parameters:

o Parameter 1(int): Upper limit.
o Parameter 2(int): Lower limit.


ΓòÉΓòÉΓòÉ 15.3.9.55. DAC_SPIN_TEXTLIMIT ΓòÉΓòÉΓòÉ

DAC_SPIN_TEXTLIMIT

This message sets the maximum number of characters allowed in the spin control.
The default limit of the spin field is 255 characters, which is the default.

Parameters:

o Parameter 1(int): numeric value.


ΓòÉΓòÉΓòÉ 15.3.9.56. DAC_SPIN_OVERRIDELIMITS ΓòÉΓòÉΓòÉ

DAC_SPIN_OVERRIDLIMITS

This message causes the spin control to set or reset numeric limits.  This
message is functionally identical to DAC_SPIN_LIMITS, except that the current
value of the spin button does not change if it is out of range.

Parameters:

o Parameter 1(int): Upper limit.
o Parameter 2(int): Lower limit.


ΓòÉΓòÉΓòÉ 15.3.9.57. DAC_SPIN_UP ΓòÉΓòÉΓòÉ

DAC_SPIN_UP

This message causes the spin control to show the next value.

Parameters: A long data value that determines how many units to spin forward.


ΓòÉΓòÉΓòÉ 15.3.9.58. DAC_SPIN_VALUE ΓòÉΓòÉΓòÉ

DAC_SPIN_VALUE

This message causes the spin control to set or reset the current numeric value.

Parameters:

o Parameter 1(int): numeric value.


ΓòÉΓòÉΓòÉ 15.3.9.59. DAC_UNCHECK ΓòÉΓòÉΓòÉ

DAC_UNCHECK

The DAC_UNCHECK flag removes a check mark on a tristate, checkbox, or radio
button.

Example:
   set_dialog_item(dlgid, control_index, DAC_UNCHECK)


ΓòÉΓòÉΓòÉ 15.3.9.60. DAC_UNDO ΓòÉΓòÉΓòÉ

DAC_UNDO

Example:
   set_dialog_item(dlgd, control_index, DAC_UNDO)


ΓòÉΓòÉΓòÉ 15.3.9.61. DAC_UNSELECT_ITEM ΓòÉΓòÉΓòÉ

DAC_UNSELECT_ITEM

Example:
   set_dialog_item(dlgd, control_index, DAC_UNSELECT_ITEM)


ΓòÉΓòÉΓòÉ 15.3.9.62. DAC_VS_QUERY_ITEM ΓòÉΓòÉΓòÉ

DAC_VS_QUERY_ITEM

Queries the contents of the item indicated by the valuaes of the row and column
parameters.

Parameters:  A long data value containing the row and column.  The row is
contained in the high word and the column is contained in the low word of the
parameter.


ΓòÉΓòÉΓòÉ 15.3.9.63. DAC_VS_QUERY_METRICS ΓòÉΓòÉΓòÉ

DAC_VS_QUERY_METRICS

Queries the current size of each value set or for the spacing between items.
The return value is either the width and height of one item, or the spacing
between items.

Parameters:  One parameter is accepted, containing:

0 - query width and height of each item
1 - query horizontal and vertical spacing between items

The queried values are returned in a long integer as follows:

low word of return value - height
high word of return value - width
low word of return value - vertical spacing
high word of return value - horizontal spacing


ΓòÉΓòÉΓòÉ 15.3.9.64. DAC_VS_QUERY_SELECTED ΓòÉΓòÉΓòÉ

DAC_VS_QUERY_SELECTED

Queries the currently selected value set item.

Returns:  LOWORD(Row) and HIWORD(Col) - row and column encoded into a long
integer.


ΓòÉΓòÉΓòÉ 15.3.9.65. DAC_VS_SELECT_ITEM ΓòÉΓòÉΓòÉ

DAC_VS_SELECT_ITEM

Selects a value set cell.

Parameters:

Parameter 1 (long) row of cell to select. Row's begin numbering at 1.
Parameter 2 (long) column of cell to select. Column's begin numbering at 1.


ΓòÉΓòÉΓòÉ 15.3.9.66. DAC_VS_SET_ITEM ΓòÉΓòÉΓòÉ

DAC_VS_SET_ITEM

Specifies the type of information that will be contained by a value set item.

Parameters:

Parameter 1 (long) row of item
Parameter 2 (long) column of item
Parameter 3 (long) data

The value of Parameter 3 depends on the VIA_* attributes set for the item:

If VIA_TEXT attribute is specified, then Parameter 3 is a string.

If VIA_RGB attribute is specified, then Parameter 3 is a RGB value.

If VIA_COLORINDEX attribute is specified, then Parameter 3 is the index of the
color in the logical color table.


ΓòÉΓòÉΓòÉ 15.3.9.67. DAC_VS_SET_METRICS ΓòÉΓòÉΓòÉ

DAC_VS_SET_METRICS

Sets the size of each item or the spacing between items in a value set control.

Parameters: Two parameters are accepted:

Parameter 1

   o 0 - set the width and height of each item
   o 1 - set the horizontal and vertical spacing between items

Parameter 2

   o If parameter 1 is 0: An int type with the width in the low word and the
     height in the high word.
   o If parameter 1 is 1: An int type with the horizontal spacing in the low
     word and the vertical spacing in the high word.


ΓòÉΓòÉΓòÉ 15.3.9.68. DAC_FG_COLOR ΓòÉΓòÉΓòÉ

DAC_FG_COLOR

Sets the foreground color of a static text control.

Parameter is a RGB value containing the new color.


ΓòÉΓòÉΓòÉ 15.3.9.69. DAC_BG_COLOR ΓòÉΓòÉΓòÉ

DAC_BG_COLOR

Sets the background color of a static text control.  Parameter is a RGB value
containing the new color.


ΓòÉΓòÉΓòÉ 15.3.9.70. DAC_SELECT_INDEX_RANGE ΓòÉΓòÉΓòÉ

DAC_SELECT_INDEX_RANGE

The DAC_SELECT_INDEX_RANGE flag selects a range of items in a list box given a
range of zero based index values.

The following example selects the items in the list box between index 3 and 6
inclusive.
   set_dialog_item(dlgid, listbox_index, DAC_DESLECTINDEX, 3, 6)


ΓòÉΓòÉΓòÉ 15.3.9.71. DAC_DESELECT_INDEX_RANGE ΓòÉΓòÉΓòÉ

DAC_DESELECT_INDEX_RANGE

The DAC_DESELECT_INDEX_RANGE flag de-selects a range of items in a list box
given a range of zero based index values.

The following example de-selects the items in the list box between index 3 and
6 inclusive.
   set_dialog_item(dlgid, listbox_index, DAC_DESLECTINDEX, 3, 6)


ΓòÉΓòÉΓòÉ 15.3.9.72. DAC_INSERT_PAGE_AT_TOP ΓòÉΓòÉΓòÉ

DAC_INSERT_PAGE_AT_TOP

The DAC_INSERT_PAGE_AT_TOP flag inserts a page at the beginning of a notebook
control. The DAC_INSERT_PAGE_AT_TOP flag takes one required parameter and five
optional parameters.

Parameters:

o Parameter 1(required): Page id returned from the create_page() function.
o Parameter 2(optional): Text to be displayed on the status line.
o Parameter 3(optional): Text to be displayed on the for the page.
o Parameter 4(optional): Type of tab.  See DAC_SET_TAB_TYPE.
o Parameter 5(optional): Display status text (TRUE) or not (FALSE)
o Parameter 6(optional): Auto page size on (TRUE) or off (FALSE). Resizes the
  notebook page whenever the notebook control is resized.

The following example inserts a page at the beginning of an existing notebook
control. The page is created with a status line with the text "Status line
text" initially displayed on the status line.  The tab is displayed as a major
tab with the text "Tab Text".
   set_dialog_item(dlgid, notebook_index, DAC_INSERT_PAGE_AT_TOP,
page_id, "Status line text",            "Tab Text", NBTAB_MAJOR, TRUE)

The next example simply creates a default page with no status bar and no major
or minor tab.
   set_dialog_item(dlgid, notebook_index, DAC_INSERT_PAGE_AT_TOP, page_id)


ΓòÉΓòÉΓòÉ 15.3.9.73. DAC_INSERT_PAGE_BEFORE ΓòÉΓòÉΓòÉ

DAC_INSERT_PAGE_BEFORE

The DAC_INSERT_PAGE_BEFORE flag inserts a page before another page of a
notebook control. The DAC_INSERT_PAGE_BEFORE flag takes two required parameters
and five optional parameters.

Parameters:

o Parameter 1(required): Page id returned from the create_page() function.
o Parameter 2(required): Page id to insert page before.
o Parameter 3(optional): Text to be displayed on the status line.
o Parameter 4(optional): Text to be displayed on the for the page.
o Parameter 5(optional): Type of tab.  See DAC_SET_TAB_TYPE.
o Parameter 6(optional): Display status text (TRUE) or not (FALSE)
o Parameter 7(optional): Auto page size on (TRUE) or off (FALSE). Resizes the
  notebook page whenever the notebook control is resized.

The following example inserts a page before another page of an existing
notebook control. The page is created with a status line with the text "Status
line text" initially displayed on the status line.  The tab is displayed as a
major tab with the text "Tab Text".
   set_dialog_item(dlgid, notebook_index, DAC_INSERT_PAGE_BEFORE,
page_id, page_id_before, "Status line text",            "Tab Text",
NBTAB_MAJOR, TRUE)

The next example simply creates a default page with no status bar and no major
or minor tab.
   set_dialog_item(dlgid, notebook_index,            DAC_INSERT_PAGE_BEFORE,
page_id, page_id_before)


ΓòÉΓòÉΓòÉ 15.3.9.74. DAC_INSERT_PAGE_AFTER ΓòÉΓòÉΓòÉ

DAC_INSERT_PAGE_AFTER

The DAC_INSERT_PAGE_AFTER flag inserts a page after another page of a notebook
control. The DAC_INSERT_PAGE_AFTER flag takes two required parameters and five
optional parameters.

Parameters:

o Parameter 1(required): Page id returned from the create_page() function.
o Parameter 2(required): Page id to insert page after.
o Parameter 3(optional): Text to be displayed on the status line.
o Parameter 4(optional): Text to be displayed on the for the page.
o Parameter 5(optional): Type of tab.  See DAC_SET_TAB_TYPE.
o Parameter 6(optional): Display status text (TRUE) or not (FALSE)
o Parameter 7(optional): Auto page size on (TRUE) or off (FALSE). Resizes the
  notebook page whenever the notebook control is resized.

The following example inserts a page after another page of an existing notebook
control. The page is created with a status line with the text "Status line
text" initially displayed on the status line.  The tab is displayed as a major
tab with the text "Tab Text".
   set_dialog_item(dlgid, notebook_index, DAC_INSERT_PAGE_AFTER,
page_id, page_id_before, "Status line text",            "Tab Text",
NBTAB_MAJOR, TRUE)

The next example simply creates a default page with no status bar and no major
or minor tab.
   set_dialog_item(dlgid, notebook_index,            DAC_INSERT_PAGE_AFTER,
page_id, page_id_before)


ΓòÉΓòÉΓòÉ 15.3.9.75. DAC_SETFOCUS ΓòÉΓòÉΓòÉ

DAC_SETFOCUS

The DAC_SETFOCUS flag sets the focus to the specified control in a dialog box.

The following example sets focus to a particular dialog control
(control_index):
   set_dialog_item(dlgid, control_index, DAC_SETFOCUS)


ΓòÉΓòÉΓòÉ 15.3.9.76. DAC_ENABLE ΓòÉΓòÉΓòÉ

DAC_ENABLE

The DAC_ENABLE flag enables a particular dialog control for input. All controls
that are enabled allow the user to input information into them either with the
mouse or keyboard.

The following example enables a particular dialog control (control_index):
   set_dialog_item(dlgid, control_index, DAC_ENABLE)


ΓòÉΓòÉΓòÉ 15.3.9.77. DAC_DISABLE ΓòÉΓòÉΓòÉ

DAC_DISABLE

The DAC_DISABLE flag disables a particular dialog control for input. All
controls that are disabled do not allow the user to input information with
either the mouse or keyboard.

The following example disables a particular dialog control (control_index):
   set_dialog_item(dlgid, control_index, DAC_DISABLE)


ΓòÉΓòÉΓòÉ 15.3.9.78. DAC_HIDE ΓòÉΓòÉΓòÉ

DAC_HIDE

The DAC_HIDE flag hides a particular dialog control so it is not seen by the
user.

The following example hides a particular dialog control (control_index):
   set_dialog_item(dlgid, control_index, DAC_HIDE)


ΓòÉΓòÉΓòÉ 15.3.9.79. DAC_SHOW ΓòÉΓòÉΓòÉ

DAC_SHOW

The DAC_SHOW flag shows a particular dialog control so it can be seen by the
user.

The following example shows a particular dialog control (control_index):
   set_dialog_item(dlgid, control_index, DAC_SHOW)


ΓòÉΓòÉΓòÉ 15.3.9.80. DAC_TEXT ΓòÉΓòÉΓòÉ

DAC_TEXT

The DAC_TEXT flag sets the text field of a control.  Not all controls have text
fields associated with them, for example list boxes.  The text field is the
text displayed with the control. For example, the text field of a group box is
the text displayed at the top of the group box.

The following example sets the text of a control to "Text Set":
   set_dialog_item(dlgid, control_index, DAC_TEXT, "Text Set")


ΓòÉΓòÉΓòÉ 15.3.9.81. DAC_SIZE ΓòÉΓòÉΓòÉ

DAC_SIZE

The DAC_SIZE flag sets the size in pixels of a dialog control.

The following example sets the size of a control to 50 pixels wide by 100
pixels height:
   set_dialog_item(dlgid, control_index, DAC_SIZE, 50, 100)


ΓòÉΓòÉΓòÉ 15.3.9.82. DAC_POSITION ΓòÉΓòÉΓòÉ

DAC_POSITION

The DAC_POSITION flag sets the position in pixels of a dialog control. The
origin(0,0) used for positioning is the lower left corner of the dialog box.  Y
values increase up and X values increase to the right.

The following example positions a control 50 pixels from the bottom by 100
pixels from the right:
   set_dialog_item(dlgid, control_index, DAC_POSITION, 50, 100)


ΓòÉΓòÉΓòÉ 15.4. Editor System ΓòÉΓòÉΓòÉ

EWC_
          Constants used to set and query editor window properties
COLOR_
          Color name constants.
SAVE_
          Constants used as masks for the save_flags variable.
STB_
          Masks for the statusbar_flags variable.
autosave_force_time
          Sets the time interval between auto-saves.
autosave_time
          Sets the idle time interval for auto-save.
backup_directory
          Names the directory where backup files are stored.
beep_string()
          String played by the beep() function.
color_linecommands_bg
          Defines background color used to draw text.
color_linecommands_fg
          Defines foreground color used to draw text.
color_linenumbers_bg
          Defines background color used to draw text.
color_linenumbers_fg
          Defines foreground color used to draw text.
color_message_bg
          Defines background color used to draw text.
color_message_fg
          Defines foreground color used to draw text.
color_notify_bg
          Defines background color used to draw text.
color_notify_fg
          Defines foreground color used to draw text.
color_warning_bg
          Defines background color used to draw text.
color_warning_fg
          Defines foreground color used to draw text.
color_window_bg
          Defines background color used to draw text.
color_window_fg
          Defines foreground color used to draw text.
current_command()
          Stores the id of the most recently invoked function.
current_key()
          Stores most recent keystroke received from keyboard.
cursor_normal
          Store the shape of the normal editing cursor.
cursor_overtype
          Store the cursor shape used in overtype mode.
cursor_virtual
          Store shape of the cursor used when in VIRTUAL SPACE.
cursor_virtual_overtype
          Store shape of the cursor used when in VIRTUAL SPACE.
default_color_error_bg
          Defines background color used to draw text.
default_color_error_fg
          Defines foreground color used to draw text.
default_color_help_bg.
          pdefault_color_help_bg.
default_color_help_fg.
          pdefault_color_help_fg.
default_color_linecommands_bg
          Defines background color used to draw text.
default_color_linecommands_fg
          Defines foreground color used to draw text.
default_color_linenumbers_bg
          Defines background color used to draw text.
default_color_linenumbers_fg
          Defines foreground color used to draw text.
default_color_message_bg
          Defines background color used to draw text.
default_color_message_fg
          Defines foreground color used to draw text.
default_color_notify_bg
          Defines background color used to draw text.
default_color_notify_fg
          Defines foreground color used to draw text.
default_color_warning_bg
          Defines background color used to draw text.
default_color_warning_fg
          Defines foreground color used to draw text.
default_color_window_bg
          Defines background color used to draw text.
default_color_window_fg
          Defines foreground color used to draw text.
display_height
          Stores the display height in lines.
display_width
          Stores the display width in columns.
editor_ae
          Contains the name of the .ae file that the editor is using.
editor_config
          Contains the name of the config file that the editor is using.
editor_helpfile
          Contains the name of the help file that the editor is using.
editor_path_var
          Contains the name of the environment variable the editor uses to
          locate configuration files.
editor_title
          Contains the title of the editor displayed on the title bar.
emulation_mode
          Stores name of emulation in use.
emulations
          Stores the name and function name available in the editor.
pause_on_error
          Dictates whether or not to pause between messages.
prev_command
          Stores the id of the previously executed function.
prev_key
          Stores the keystroke preceding most recently received.
save_flags
          Stores what is saved in the config file on exit.
save_state
          Tells whether the editor state should be saved on exit.
temp_path
          Names directories where temporary files are made.
version
          Stores the release version number of the editor.


ΓòÉΓòÉΓòÉ 15.4.1. COLOR_ ΓòÉΓòÉΓòÉ

COLOR_   Primitive

Purpose:  Color name constants.

____________

Type:    const int COLOR_

____________

Description: The COLOR_ constants can be used to set colors in the editor. You
may use the easy to remember names like COLOR_NEON_BABY_BLUE or hard code the
equivalent number.

o COLOR_MEDVIOLET
o COLOR_NEON_BABY_BLUE
o COLOR_ORANGE
o COLOR_ORANGERED
o COLOR_ORCHID
o COLOR_PINK
o COLOR_RED
o COLOR_WHITE
o COLOR_YELLOW

____________


ΓòÉΓòÉΓòÉ 15.4.2. EWC_ ΓòÉΓòÉΓòÉ

EWC_   Primitive

Purpose:  Constants used to set and query editor window properties

____________

Type:    const int EWC_

____________

Description: The constants defined in the EWC_ category are useful when calling
functions such as set_editwin_property() and query_editwin_property(). The
constants can be passed in as the flag parameter.

o EWC_CLIENT_HEIGHT
o EWC_CLIENT_WIDTH
o EWC_DISABLE
o EWC_ENABLE
o EWC_HANDLE
o EWC_HEIGHT
o EWC_MAXIMIZE
o EWC_MINIMIZE
o EWC_NORMAL
o EWC_RESTORE_HEIGH
o EWC_RESTORE_WIDTH
o EWC_RESTORE_X_POS
o EWC_RESTORE_Y_POS
o EWC_TO_TOP
o EWC_WIDTH
o EWC_X_POS
o EWC_Y_POS

____________


ΓòÉΓòÉΓòÉ 15.4.3. SAVE_ ΓòÉΓòÉΓòÉ

SAVE_   Primitive

Purpose:  Constants used as masks for the save_flags variable.

____________

Type:    const int SAVE_

____________

Description: The constants defined in the SAVE_ section can be used as masks
for the modifying or examining  the save_flags variable.

o SAVE_COMMANDS
o SAVE_COMPILE
o SAVE_DEFAULT
o SAVE_EDITFILE
o SAVE_REPLACE
o SAVE_SEARCH
o SAVE_SETTINGS

____________


ΓòÉΓòÉΓòÉ 15.4.4. STB_ ΓòÉΓòÉΓòÉ

STB_   Primitive

Purpose:  Masks for the statusbar_flags variable.

____________

Type:    const int STB_

____________

Description: The constants defined in the STB_ section are used as masks to
modify and examine the status_bar_flags variable.

o STB_BUSY
o STB_CLOCK
o STB_COLUMN
o STB_DATE
o STB_DAYOFWEEK
o STB_DEFAULT
o STB_DEFAULT_PROMPTS
o STB_DYNA_SIZE
o STB_EMULATION
o STB_INDICATORS
o STB_LAST_LINE
o STB_LEVELS
o STB_LINE
o STB_LINE_COLUMN
o STB_MESSAGELEV0
o STB_MESSAGELEV1
o STB_MESSAGES
o STB_PAUSEONERR
o STB_POSITION
o STB_PROMPTS
o STB_TIME
o STB_TIME12
o STB_TIME24
o STB_TOTAL_INDS
o STB_VISIBLE

____________


ΓòÉΓòÉΓòÉ 15.4.5. autosave_force_time ΓòÉΓòÉΓòÉ

autosave_force_time   PEL

Purpose: Sets the time interval between auto-saves.

____________

Type:   int autosave_force_time

____________

Description:

The autosave_force_time variable contains the number of seconds between
auto-saves, without regard to keyboard activity.  This value is only meaningful
if the auto-save feature has been turned on.  The default value for this
variable is 0 seconds, which has the effect of disabling forced saves.

____________

See also:  autosave(), autosave_time


ΓòÉΓòÉΓòÉ 15.4.6. autosave_time ΓòÉΓòÉΓòÉ

autosave_time   PEL

Purpose: Sets the idle time interval for auto-save.

____________

Type:   int autosave_time

____________

Description:

The autosave_time variable contains the number of seconds that the keyboard
must be idle before the auto-save feature saves the file.  This value is only
meaningful if the auto-save feature has been turned on.  The default value for
this variable is 15 seconds.

____________

See also:  autosave(), autosave_force_time


ΓòÉΓòÉΓòÉ 15.4.7. backup_directory ΓòÉΓòÉΓòÉ

backup_directory   PEL

Purpose: Names the directory where backup files are stored.

____________

Type:   str backup_directory

____________

Description:

The backup_directory variable is the directory name where you can find backup
files.  The backup directory may be on any valid drive and directory in your
system.  It may also be specified in relative terms such as "." to indicate the
current directory or "..\backup" indicating the backup subdirectory off of the
current directory's parent directory.  By default this variable is an empty
string and uses the editor_path()\ backup directory.

Whenever this string is empty, backups are made in a default directory. The
editor attempts to save backups in a directory specified in the notebook
settings.  If this directory does not exist, the editor will attempt to create
it.  If unable to create this directory, for example on a network drive, the
editor stores backups in the directory from which the file originated.

You may specify that backups be made in the same directory where the file
originated, by giving backup_directory the value "*", a single asterisk.

____________

See also: backup_file_ext


ΓòÉΓòÉΓòÉ 15.4.8. beep_string ΓòÉΓòÉΓòÉ

beep_string   Primitive

Purpose: String played by the beep() function.

____________

Type:   str beep_string

____________

Description:

The beep_string variable is the string that is played when the beep() function
is called.  The syntax for the beep_string is the same as the string for
play().


ΓòÉΓòÉΓòÉ 15.4.9. color_ ΓòÉΓòÉΓòÉ

color_   Primitive

____________

Purpose:  Defines the various colors used by the system.

____________

Type:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariable               ΓöéScope          Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_error_fg         ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_error_bg         ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_help_fg          ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_help_bg          ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_linenumbers_fg   ΓöéWindow         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_linenumbers_bg   ΓöéWindow         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_linecommands_fg  ΓöéWindow         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_linecommands_bg  ΓöéWindow         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_message_fg       ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_message_bg       ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_notify_fg        ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_notify_bg        ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_warning_fg       ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_warning_fg       ΓöéEditor Window  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_window_fg        ΓöéWindow         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöécolor_window_bg        ΓöéWindow         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

____________

Description:

The system-wide and window-specific variables listed above define the colors to
be used for various aspects of the editor's appearance.  Of these variables
several are system-wide, while the rest may be defined differently for each
window in use.

The initial values for the color variables are obtained from the like-named
default_ variables at the time the object (window or status bar) is created.
If window variables are modified after the window has been created, a call to
the update_current_view() function is required to ensure consistent appearance.

Permissible values for color_ variables are shown in a table in the "Windowing"
section in Part One of this manual.


ΓòÉΓòÉΓòÉ 15.4.10. color_help_bg ΓòÉΓòÉΓòÉ

color_help_bg   Primitive

Purpose: Defines background color used to draw help text.

____________

Type: int color_help_bg

____________

Description:

Each editor window has a color_help_bg variable associated with it.  This
variable contains the background color of help text when help is displayed on
the status bar.

The initial value is copied from the global variable default_color_help_bg.

____________

See also:  help(), color_message_fg, color_message_fg, color_help_fg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.11. color_help_fg ΓòÉΓòÉΓòÉ

color_help_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_help_fg

____________

Description:

Each editor window has a color_help_fg variable associated with it.  This
variable contains the foreground color of help text when help is displayed on
the status bar.

The initial value is copied from the global variable default_color_help_fg.

____________

See also:   help(), color_message_bg, color_message_fg, color_help_bg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.12. color_linecommands_bg ΓòÉΓòÉΓòÉ

color_linecommands_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_linecommands_bg

____________

Description:

Each window has a color_linecommands_bg variable associated with it.  This
variable contains the background color of text displayed when entering
linecommands in the linenumber area.

The initial value is copied from the global variable
default_color_linecommands_bg.

____________

See also:   color_window_bg, color_window_fg, color_linenumbers_fg,
color_linenumbers_fg, color_linecommands_fg


ΓòÉΓòÉΓòÉ 15.4.13. color_linecommands_fg ΓòÉΓòÉΓòÉ

color_linecommands_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_linecommands_fg

____________

Description:

Each window has a color_linecommands_fg variable associated with it.  This
variable contains the foreground color of text displayed when entering
linecommands in the linenumber area.

The initial value is copied from the global variable
default_color_linecommands_fg.

____________

See also:   color_window_bg, color_window_fg, color_linenumbers_bg,
color_linenumbers_fg, color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.14. color_linenumbers_bg ΓòÉΓòÉΓòÉ

color_linenumbers_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_linenumbers_bg

____________

Description:

Each window has a color_linenumbers_bg variable associated with it.  This
variable contains the background color of text displayed in the linenumber area
of a window.

The initial value is copied from the global variable
default_color_linenumbers_bg.

____________

See also:   color_window_bg, color_window_fg, color_linenumbers_fg,
color_linecommands_fg, color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.15. color_linenumbers_fg ΓòÉΓòÉΓòÉ

color_linenumbers_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_linenumbers_fg

____________

Description:

Each window has a color_linenumbers_fg variable associated with it.  This
variable contains the foreground color of text displayed in the linenumber area
of a window.

The initial value is copied from the global variable
default_color_linenumbers_fg.

____________

See also:   color_window_bg, color_window_fg, color_linenumbers_bg,
color_linecommands_fg, color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.16. color_message_bg ΓòÉΓòÉΓòÉ

color_message_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_message_bg

____________

Description:

Each editor window has a color_message_bg variable associated with it.  This
variable contains the background color of message text when messages are
displayed on the status bar.

The initial value is copied from the global variable default_color_message_bg.

____________

See also:  message(), color_message_fg, color_notify_fg, color_notify_bg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.17. color_message_fg ΓòÉΓòÉΓòÉ

color_message_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_message_fg

____________

Description:

Each editor window has a color_message_fg variable associated with it.  This
variable contains the foreground color of message text when messages are
displayed on the status bar.

The initial value is copied from the global variable default_color_message_fg.

____________

See also:  message(), color_message_bg, color_notify_fg, color_notify_bg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.18. color_notify_bg ΓòÉΓòÉΓòÉ

color_notify_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_notify_bg

____________

Description:

Each editor window has a color_notify_bg variable associated with it.  This
variable contains the background color of notify text when notifications are
displayed on the status bar.

The initial value is copied from the global variable default_color_notify_bg.

____________

See also:  notify(), color_message_fg, color_message_fg, color_notify_fg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.19. color_notify_fg ΓòÉΓòÉΓòÉ

color_notify_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_notify_fg

____________

Description:

Each editor window has a color_notify_fg variable associated with it.  This
variable contains the foreground color of notify text when notifications are
displayed on the status bar.

The initial value is copied from the global variable default_color_notify_fg.

____________

See also:   notify(), color_message_bg, color_message_fg, color_notify_bg,
color_warning_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.20. color_warning_bg ΓòÉΓòÉΓòÉ

color_warning_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_warning_bg

____________

Description:

Each editor window has a color_warning_bg variable associated with it.  This
variable contains the background color of warning text when warnings are
displayed on the status bar.

The initial value is copied from the global variable default_color_warning_bg.

____________

See also:  warning(), color_message_fg, color_message_fg, color_notify_fg,
color_notify_fg, color_warning_fg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.21. color_warning_fg ΓòÉΓòÉΓòÉ

color_warning_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_warning_fg

____________

Description:

Each editor window has a color_warning_fg variable associated with it.  This
variable contains the foreground color of warning text when warnings are
displayed on the status bar.

The initial value is copied from the global variable default_color_warning_fg.

____________

See also:   warning(), color_message_bg, color_message_fg, color_notify_bg,
color_notify_fg, color_warning_bg, color_error_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.4.22. color_window_bg ΓòÉΓòÉΓòÉ

color_window_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_window_bg

____________

Description:

Each window has a color_window_bg variable associated with it.  This variable
contains the background color of text displayed in a window.

The initial value is copied from the global variable default_color_window_bg.

____________

See also:   color_window_bg, color_linenumbers_fg, color_linenumbers_bg,
color_linecommands_fg, color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.23. color_window_fg ΓòÉΓòÉΓòÉ

color_window_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_window_fg

____________

Description:

Each window has a color_window_fg variable associated with it.  This variable
contains the foreground color of text displayed in a window.

The initial value is copied from the global variable default_color_window_fg.

____________

See also:   color_window_bg, color_linenumbers_fg, color_linenumbers_bg,
color_linecommands_fg, color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.24. current_command ΓòÉΓòÉΓòÉ

current_command  read-only   Primitive

Purpose: Stores the id of the most recently invoked function.

____________

Type: funcid current_command

____________

Description:

The current_command variable contains the function id of the function that was
most recently executed from the keyboard.  This includes any functions which
have been assigned to keys.  This variable does not necessarily reflect the
function currently being executed.

The function id stored in current_command may be converted to a string
containing the name of the function.  This is done through use of the
function_name() function.  This variable may only be modified by the system.

____________

See also:  function_caller(), prev_command


ΓòÉΓòÉΓòÉ 15.4.25. current_key ΓòÉΓòÉΓòÉ

current_key read-only   Primitive

Purpose: Stores most recent keystroke received from keyboard.

____________

Type: funcid current_command

____________

Description:

The current_key variable contains the value of the most recent key combination
entered by the user.  If the key pressed was an ordinary character, its ASCII
value will be found in the least significant byte and the scan code is in the
high byte of current_key.  If, however, the key returned an extended code, the
least significant byte will be null and the code will be in the second byte of
current_key.

____________

See also:  prev_key


ΓòÉΓòÉΓòÉ 15.4.26. cursor_normal ΓòÉΓòÉΓòÉ

cursor_normal.   Primitive

Purpose: Store the shape of the normal editing cursor.

____________

Type:   int cursor_normal

____________

Description:

The shape of the normal (insert mode) cursor is stored in the least significant
two bytes or the variable cursor_normal.

This variable may be set by the user.  The high byte contains the color of the
cursor.  If the high byte contains 0x80 the cursor is gray, otherwise the
cursor is the screen inverse color. If the lower byte is set to 0x02 then the
cursor is a thin vertical line.  The cursor is a solid block if the lower byte
is 0x01.

____________

See also:  cursor_overtype, cursor_virtual_overtype, cursor_virtual


ΓòÉΓòÉΓòÉ 15.4.27. cursor_overtype ΓòÉΓòÉΓòÉ

cursor_overtype   Primitive

Purpose: Store the cursor shape used in overtype mode.

____________

Type:   int cursor_overtype

____________

Description:

The shape of the cursor displayed when in the overtype editing mode.

The storage format used is the same as in the description of cursor_normal.

____________

See also:  cursor_virtual, cursor_virtual_overtype, cursor_normal


ΓòÉΓòÉΓòÉ 15.4.28. cursor_virtual ΓòÉΓòÉΓòÉ

cursor_virtual   Primitive

Purpose: Store shape of the cursor used when in VIRTUAL SPACE.

____________

Type:   int cursor_virtual

____________

Description:

The shape of the cursor displayed when it is positioned outside the buffer's
existing line boundaries or in space resulting from tabs (virtual space) is
stored in the variable cursor_virtual.

The storage format used is the same as in the description of cursor_normal.

____________

See also:  cursor_overtype, cursor_virtual_overtype, cursor_normal


ΓòÉΓòÉΓòÉ 15.4.29. cursor_virtual_overtype ΓòÉΓòÉΓòÉ

cursor_virtual_overtype   Primitive

Purpose: Store shape of the cursor used when in VIRTUAL SPACE.

____________

Type:   int cursor_virtual_overtype

____________

Description:

The cursor_virtual_overtype variable stores the cursor shape displayed when it
is positioned in virtual space and overtype mode is in effect.  virtual space
is the area outside the buffer's existing line boundaries and the area created
by tabs.

The storage format used is the same as described in cursor_normal.

____________

See also:  cursor_overtype, cursor_normal, cursor_virtual


ΓòÉΓòÉΓòÉ 15.4.30. default_color_error_bg ΓòÉΓòÉΓòÉ

default_color_error_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_error_bg

____________

Description:

The default_color_error_bg variable contains the initial value of the
color_error_bg variable when a new editor window is created.

____________

See also:  color_error_bg


ΓòÉΓòÉΓòÉ 15.4.31. default_color_error_fg ΓòÉΓòÉΓòÉ

default_color_error_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_error_fg

____________

Description:

The default_color_error_fg variable contains the initial value of the
color_error_fg variable when a new editor window is created.

____________

See also:  color_error_fg


ΓòÉΓòÉΓòÉ 15.4.32. default_color_help_bg ΓòÉΓòÉΓòÉ

default_color_help_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_help_bg

____________

Description:

The default_color_help_bg variable contains the initial value of the
color_help_bg variable when a new editor window is created.

____________

See also:  color_help_bg


ΓòÉΓòÉΓòÉ 15.4.33. default_color_help_fg ΓòÉΓòÉΓòÉ

default_color_help_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_help_fg

____________

Description:

The default_color_help_fg variable contains the initial value of the
color_help_fg variable when a new editor window is created.

____________

See also:  color_help_fg


ΓòÉΓòÉΓòÉ 15.4.34. default_color_linecommands_bg ΓòÉΓòÉΓòÉ

default_color_linecommands_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_linecommands_bg

____________

Description:

The default_color_linecommands_bg variable contains the initial value of the
color_linecommands_bg variable when a new text window is created.

____________

See also:  color_linecommands_bg


ΓòÉΓòÉΓòÉ 15.4.35. default_color_linecommands_fg ΓòÉΓòÉΓòÉ

default_color_linecommands_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_linecommands_fg

____________

Description:

The default_color_linecommands_fg variable contains the initial value of the
color_linecommands_fg variable when a new text window is created.

____________

See also:  color_linecommands_fg


ΓòÉΓòÉΓòÉ 15.4.36. default_color_linenumbers_bg ΓòÉΓòÉΓòÉ

default_color_linenumbers_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_linenumbers_bg

____________

Description:

The default_color_linenumbers_bg variable contains the initial value of the
color_linenumbers_bg variable when a new text window is created.

____________

See also:  color_linenumbers_bg


ΓòÉΓòÉΓòÉ 15.4.37. default_color_linenumbers_fg ΓòÉΓòÉΓòÉ

default_color_linenumbers_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_linenumbers_fg

____________

Description:

The default_color_linenumbers_fg variable contains the initial value of the
color_linenumbers_fg variable when a new text window is created.

____________

See also:  color_linenumbers_fg


ΓòÉΓòÉΓòÉ 15.4.38. default_color_message_bg ΓòÉΓòÉΓòÉ

default_color_message_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_message_bg

____________

Description:

The default_color_message_bg variable contains the initial value of the
color_message_bg variable when a new editor window is created.

____________

See also:  color_message_fg


ΓòÉΓòÉΓòÉ 15.4.39. default_color_message_fg ΓòÉΓòÉΓòÉ

default_color_message_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_message_fg

____________

Description:

The default_color_message_fg variable contains the initial value of the
color_message_fg variable when a new editor window is created.

____________

See also:  color_message_fg


ΓòÉΓòÉΓòÉ 15.4.40. default_color_notify_bg ΓòÉΓòÉΓòÉ

default_color_notify_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_notify_bg

____________

Description:

The default_color_notify_bg variable contains the initial value of the
color_notify_bg variable when a new editor window is created.

____________

See also:  color_notify_bg


ΓòÉΓòÉΓòÉ 15.4.41. default_color_notify_fg ΓòÉΓòÉΓòÉ

default_color_notify_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_notify_fg

____________

Description:

The default_color_notify_fg variable contains the initial value of the
color_notify_fg variable when a new editor window is created.

____________

See also:  color_notify_fg


ΓòÉΓòÉΓòÉ 15.4.42. default_color_warning_bg ΓòÉΓòÉΓòÉ

default_color_warning_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_warning_bg

____________

Description:

The default_color_warning_bg variable contains the initial value of the
color_warning_bg variable when a new editor window is created.

____________

See also:  color_warning_bg


ΓòÉΓòÉΓòÉ 15.4.43. default_color_warning_fg ΓòÉΓòÉΓòÉ

default_color_warning_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_warning_fg

____________

Description:

The default_color_warning_fg variable contains the initial value of the
color_warning_fg variable when a new editor window is created.

____________

See also:  color_warning_fg


ΓòÉΓòÉΓòÉ 15.4.44. default_color_window_bg ΓòÉΓòÉΓòÉ

default_color_window_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int default_color_window_bg

____________

Description:

The default_color_window_bg variable contains the initial value of the
color_window_bg variable when a new text window is created.

____________

See also:  color_window_bg


ΓòÉΓòÉΓòÉ 15.4.45. default_color_window_fg ΓòÉΓòÉΓòÉ

default_color_window_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int default_color_window_fg

____________

Description:

The default_color_window_fg variable contains the initial value of the
color_window_fg variable when a new text window is created.

____________

See also:  color_window_fg


ΓòÉΓòÉΓòÉ 15.4.46. display_height ΓòÉΓòÉΓòÉ

display_height  read-only   Primitive

Purpose: Stores the display height in lines.

____________

Type:   int display_height

____________

Description: The display_height variable contains the number of lines that are
currently displayed.  This variable is maintained by the system and may not be
modified by the user.

____________

See also:  display_width


ΓòÉΓòÉΓòÉ 15.4.47. display_width ΓòÉΓòÉΓòÉ

display_width  read-only   Primitive

Purpose: Stores the display width in columns.

____________

Type:   int display_width

____________

Description:

The display_width variable contains the number of columns are currently
displayed. This variable is maintained by the system and may not be modified by
the user.

____________

See also:  display_height


ΓòÉΓòÉΓòÉ 15.4.48. editor_ae ΓòÉΓòÉΓòÉ

editor_ae  Read-Only   Primitive

Purpose: Contains the name of the .ae file that the editor is using.

____________

Type:   str editor_ae

____________

Description:

The editor_ae variable contains the name of the .ae file that is used by the
editor.  The default .ae file used is cpe.ae.  This can be changed by a command
line option passed to the editor when it is started.


ΓòÉΓòÉΓòÉ 15.4.49. editor_config ΓòÉΓòÉΓòÉ

editor_config   read only   Primitive

Purpose: Contains the name of the config file that the editor is using.

____________

Type:   str editor_config

____________

Description:

The editor_config variable contains the name of the configuration file used by
the editor.  The default configuration file used is cpe.cfg.


ΓòÉΓòÉΓòÉ 15.4.50. editor_helpfile ΓòÉΓòÉΓòÉ

editor_helpfile Read-Only   Primitive

Purpose: Contains the name of the help file that the editor is using.

____________

Type:   str editor_helpfile

____________

Description:

The editor_helpfile variable contains the name of the .hlp file the editor is
currently using.  This value is set to cpe.hlp by default.


ΓòÉΓòÉΓòÉ 15.4.51. editor_path_var ΓòÉΓòÉΓòÉ

editor_path_var  Read-Only   Primitive

Purpose: Contains the name of the environment variable the editor uses to
locate configuration files.

____________

Type:   str editor_path_var

____________

Description:

The editor_path_var variable contains the name of the evironment variable used
by the editor to locate system and configuration files.


ΓòÉΓòÉΓòÉ 15.4.52. editor_title ΓòÉΓòÉΓòÉ

editor_title Read-Only   Primitive

Purpose: Contains the title of the editor displayed on the title bar.

____________

Type:   str editor_title

____________

Description:

The editor_title variable contains the title that the editor displays on it's
main title bar.


ΓòÉΓòÉΓòÉ 15.4.53. emulation_mode ΓòÉΓòÉΓòÉ

emulation_mode   Primitive

Purpose: Stores name of emulation in use.

____________

Type:   str emulation_mode

____________

Description:

This variable is set by the various emulation modes to contain the name of the
mode currently in use.


ΓòÉΓòÉΓòÉ 15.4.54. emulations ΓòÉΓòÉΓòÉ

emulations   PEL

Purpose:  Stores the name and function name available in the editor.

____________

Type:    str emulations[]

____________

Description: The emulations[] array is used to keep track of the emulation
modes available to the user.  The index in the function name used to initialize
the emualtion, and the element is a text string that is used for display in the
settings_notebook() and Quick Settings.  If you define your own emulation and
would like it to appear in the notebooks, you must add it to this array.

____________

See also:

o emulation_mode


ΓòÉΓòÉΓòÉ 15.4.55. pause_on_error ΓòÉΓòÉΓòÉ

pause_on_error   Primitive

Purpose: Dictates whether or not to pause between messages.

____________

Type: int pause_on_error

____________

Description: When the pause_on_error variable is a non-zero value, the editor
will pause after each error or warning message until some input is received
from the keyboard.  By default a message box is displayed that requires user
input before continuing.  After receiving input, the next message, if any, is
displayed.

When this variable is set to zero, messages are displayed as fast as they are
generated on the status bar.  In some instances, this will not provide
sufficient time for messages to be read.

____________

See also:   warning(), error()


ΓòÉΓòÉΓòÉ 15.4.56. prev_command ΓòÉΓòÉΓòÉ

prev_command  read-only   Primitive

Purpose: Stores the id of the previously executed function.

____________

Type: funcid prev_command

____________

Description: The prev_command variable contains the function id of the function
executed from the keyboard immediately preceding the current.  This includes
any functions which have been assigned to keys.

The function id stored in prev_command may be converted to a string containing
the name of the function.  This is done through use of the function_name()
function.  This variable may only be modified by the system.

____________

See also:   function_caller(), current_command()


ΓòÉΓòÉΓòÉ 15.4.57. prev_key ΓòÉΓòÉΓòÉ

prev_key  read-only   Primitive

Purpose: Stores the keystroke preceding most recently received.

____________

Type: int prev_key

____________

Description: The prev_key variable contains the value of key combination that
preceded the keystroke most recently entered by the user.  If the key pressed
was an ordinary character, its ASCII value will be found in the least
significant byte of prev_key. If, however, the key returned an extended code,
the least significant byte will be null and the code will be in the second byte
of prev_key.

____________

See also:  current_key()


ΓòÉΓòÉΓòÉ 15.4.58. save_flags ΓòÉΓòÉΓòÉ

save_flags   PEL

Purpose:  Stores what is saved in the config file on exit.

____________

Type:    int save_flags

____________

Description: The save_flags variable indicates what will be saved upon exit of
the editor.  The save settings may be set on the save page of the settings
notebook or set manually with the help of the masks listed in the SAVE_
section.

____________


ΓòÉΓòÉΓòÉ 15.4.59. save_state ΓòÉΓòÉΓòÉ

save_state  PEL   PEL

Purpose: Tells whether the editor state should be saved on exit.

____________

Type: int save_state

____________

Description: The save_state variable dictates whether or not the editor will
save certain information about its state in the configuration file when
exiting.  This information may then be used later to restore the state which
existed at exit.

The file in which this information is saved is named CPE.CFG in the $STATE$
section.  It resides in the editor Home Directory or in the directory pointed
to by the CPE environment variable.  Among the status information that can be
stored in the configuration file are details about each buffer and window.

The buffer information which is stored in the CPE.CFG file includes:  the
buffer name, the filename associated with the buffer, the buffer flags, the
current line and column position within the buffer and the tab settings.

The window information which is stored in the CPE.CFG file includes: the window
name, visible_ .. strings, linenumber format, window colors, scroll variables,
font information, and buffers visible in windows.

By default, save_state is set to a one (TRUE) value.  When this variable is
zero, state information is not saved on exit and any state information
previously stored is not used.

If no file is specified for editing when you invoke the editor and save_state
is TRUE, the editor will define each of the buffers and windows described in
the configuration file.  In addition, state values stored in the configuration
file are assigned to the appropriate variables.  The result is a state very
similar to the one which existed when you last exited the editor. If a file to
edit is specified on the command line the state information is not used
regardless of the condition of the save_state variable.


ΓòÉΓòÉΓòÉ 15.4.60. temp_path ΓòÉΓòÉΓòÉ

temp_path   Primitive

Purpose: Names directories where temporary files are made.

____________

Type: str temp_path

____________

Description: The temp_path variable contains the name of the directory where
the editor creates temporary files, when necessary.

The initial value for this variable is taken from two environment variables.
If a TMP environment variable has been defined, the directory it names becomes
the first directory in the temp_path list. If an environment variable named
TEMP has been defined, the directory named by that variable is added to
temp_path.

Normally the user concatenates other directory names onto the temp_path
variable without removing existing directory names.


ΓòÉΓòÉΓòÉ 15.4.61. version ΓòÉΓòÉΓòÉ

version   Primitive

Purpose: Stores the release version number of the editor.

____________

Type: str version

____________

Description: The version constant contains the release version number of the
editor executable currently in use.  Consulting this variable enables the user
or user written function to determine what features are available.


ΓòÉΓòÉΓòÉ 15.5. Event Handling ΓòÉΓòÉΓòÉ

EVENT.
          Constant names for editor events.
idle_threshold
          Sets length of inactivity which triggers an event.
idle_time
          Tells the number of seconds since the last keystroke.


ΓòÉΓòÉΓòÉ 15.5.1. EVENT. ΓòÉΓòÉΓòÉ

EVENT.   Primitive

Purpose:  Constant names for editor events.

____________

Type:    const int EVENT.

____________

Description: The constants defined in the EVENT. section are the names for the
editor defined events.

o EVENT.BUFFER_CREATED
o EVENT.CLOSING_REMOTE_WINDOW
o EVENT.CTRL_BREAK
o EVENT.DELETE_CHARS
o EVENT.DELETING_BUFFER
o EVENT.DELETING_WINDOW
o EVENT.DISPLAY_UPDATE
o EVENT.EDITOR_RUNNING
o EVENT.EDIT_FILE_SAVE
o EVENT.EMULATION_CHANGED
o EVENT.ERROR
o EVENT.EXIT_EDITOR
o EVENT.FILE_DROPPED
o EVENT.FIRST_MOD
o EVENT.FUNCTION_CHANGED
o EVENT.HELP_INVOKED
o EVENT.IDLE_THRESHOLD
o EVENT.IDLE_TIME
o EVENT.INSERT_KEY
o EVENT.INSERT_NEWLINE
o EVENT.INSERT_STRING
o EVENT.INVALID_PCHAR
o EVENT.KEYPRESS
o EVENT.KEYPRESS_AFTER
o EVENT.LMOUSE_DRAG
o EVENT.MENU_COMMAND
o EVENT.MMOUSE_DRAG
o EVENT.MOUSE_LEFT_CLICK1
o EVENT.MOUSE_LEFT_CLICK2
o EVENT.MOUSE_LEFT_DOWN
o EVENT.MOUSE_LEFT_UP
o EVENT.MOUSE_MID_CLICK1
o EVENT.MOUSE_MID_CLICK2
o EVENT.MOUSE_MID_DOWN
o EVENT.MOUSE_MID_UP
o EVENT.MOUSE_RIGHT_CLICK1
o EVENT.MOUSE_RIGHT_CLICK2
o EVENT.MOUSE_RIGHT_DOWN
o EVENT.MOUSE_RIGHT_UP
o EVENT.NEW_CURNT_BUFFER
o EVENT.NEW_CURNT_SCREEN
o EVENT.NEW_CURNT_WINDOW
o EVENT.NEW_EDIT_FILE
o EVENT.NEW_EMPTY_BUFFER
o EVENT.NEW_SCREEN_SIZE
o EVENT.PAGECHANGED
o EVENT.PIPE_DATA
o EVENT.PROCESS_COMPLETE
o EVENT.READ_ONLY_MOD
o EVENT.RESIZE_EDITWIN
o EVENT.RMOUSE_DRAG
o EVENT.SCROLL_HORZ
o EVENT.SCROLL_VERT
o EVENT.SHELL_EXIT
o EVENT.SYSTEM_MENU_KEY
o EVENT.TEMP_SPACE_OVFLW
o EVENT.TOOLBAR_COMMAND
o EVENT_TRACKING_DONE
o EVENT.UNASSGN_KEY
o EVENT.WINDOW_MODE_CHANGE

____________

See also: attach_event_handler(), query_event().


ΓòÉΓòÉΓòÉ 15.5.2. idle_threshold ΓòÉΓòÉΓòÉ

idle_threshold   Primitive

Purpose: Sets length of inactivity which triggers an event.

____________

Type: int idle_threshold

____________

Description:

The value stored in the idle_threshold variable is the number of seconds that
may elapse without keyboard activity before the idle event is triggered.  This
threshold is reached when the idle_time variable is the same or greater than
idle_threshold.

The default value for this variable is large enough that the idle event is
effectively turned off.


ΓòÉΓòÉΓòÉ 15.5.3. idle_time ΓòÉΓòÉΓòÉ

idle_time   Primitive

Purpose: Tells the number of seconds since the last keystroke.

____________

Type: int idle_time

____________

Description:

The variable idle_time stores the elapsed time in seconds since the last input
was received from the keyboard.  This variable may be modified in order to
hasten or delay reaching the idle event threshold, defined by the
idle_threshold variable.


ΓòÉΓòÉΓòÉ 15.5.4. fast_help ΓòÉΓòÉΓòÉ

fast_help

Purpose:  Flag which toggles fast_help on or off.

____________

Type:  fast_help

____________

Description:  If this function is set to 0, the editor searches for the topic
in each NDX file to see if it is in the help file before it is added to the
list which the user selects from.  If this function is not set to 0, the editor
does not search for the topic until the user selects a help file from the
possible help files for that extension.

____________

See also:  first_help, ndx_help(), display_help_item()


ΓòÉΓòÉΓòÉ 15.5.5. first_help ΓòÉΓòÉΓòÉ

first_help

Purpose:  Flag which toggles first_help on or off.

____________

Type:  first_help

____________

Description:  If this function is not set to 0 and fast_help is set to 0, the
first NDX file that has an entry matching the desired topic is used, and no
further NDX files are searched.

____________

See also:  fast_help, ndx_help(), display_help_item()


ΓòÉΓòÉΓòÉ 15.6. Key mapping ΓòÉΓòÉΓòÉ

KEYCODE_
          Constants for commonly used keycodes.
ascii_keymap
          Predefined keyboard of just the ASCII character keys.
buffer_keymap
          Identifies keymap that locally overlays current default.
current_keymap
          Stores the id of the keymap presently in use.
default_key_action_mode
          Specifies function to be executed if a key is not assigned in the
          current keymap.
empty_keymap
          Stores id of keyboard definition with no assignments.
factory_keymap
          Predefined keyboard of standard editor keys.
playingback
          Indicates whether a keyboard macro is being played back.
recording
          Indicates whether a keyboard macro is being recorded back.
window_keymap
          Identifies the keymap that locally overlays the current default.


ΓòÉΓòÉΓòÉ 15.6.1. KEYCODE_ ΓòÉΓòÉΓòÉ

KEYCODE_   Primitive

Purpose:  Constants for commonly used keycodes.

____________

Type:    const int KEYCODE_

____________

Description: The constants defined in the KEYCODE_ section are the most
commonly used scancodes.  They can be used for checking the return value from
the key_to_int() function.

o KEYCODE_ALT
o KEYCODE_ALT_0
o KEYCODE_ALT_1
o KEYCODE_ALT_2
o KEYCODE_ALT_3
o KEYCODE_ALT_4
o KEYCODE_ALT_5
o KEYCODE_ALT_6
o KEYCODE_ALT_7
o KEYCODE_ALT_8
o KEYCODE_ALT_9
o KEYCODE_CENTER
o KEYCODE_CTRL
o KEYCODE_CTRL_AT
o KEYCODE_CTRL_CENTER
o KEYCODE_CTRL_DOWN
o KEYCODE_CTRL_END
o KEYCODE_CTRL_HOME
o KEYCODE_CTRL_LEFT
o KEYCODE_CTRL_NUM_DOWN
o KEYCODE_CTRL_NUM_END
o KEYCODE_CTRL_NUM_HOME
o KEYCODE_CTRL_NUM_LEFT
o KEYCODE_CTRL_NUM_PAGEDOWN
o KEYCODE_CTRL_NUM_PAGEUP
o KEYCODE_CTRL_NUM_RIGHT
o KEYCODE_CTRL_NUM_UP
o KEYCODE_CTRL_PAGEDOWN
o KEYCODE_CTRL_PAGEUP
o KEYCODE_CTRL_RIGHT
o KEYCODE_CTRL_UP
o KEYCODE_DOWN
o KEYCODE_END
o KEYCODE_ENTER
o KEYCODE_ESC
o KEYCODE_F1
o KEYCODE_F10
o KEYCODE_F11
o KEYCODE_F12
o KEYCODE_F2
o KEYCODE_F3
o KEYCODE_F4
o KEYCODE_F5
o KEYCODE_F6
o KEYCODE_F7
o KEYCODE_F8
o KEYCODE_F9
o KEYCODE_HOME
o KEYCODE_KEYPAD_ENTER
o KEYCODE_LEFT
o KEYCODE_NUM_DOWN
o KEYCODE_NUM_END
o KEYCODE_NUM_HOME
o KEYCODE_NUM_LEFT
o KEYCODE_NUM_PAGEDOWN
o KEYCODE_NUM_PAGEUP
o KEYCODE_NUM_RIGHT
o KEYCODE_NUM_UP
o KEYCODE_PAGEDOWN
o KEYCODE_PAGEUP
o KEYCODE_RIGHT
o KEYCODE_SHIFT
o KEYCODE_TAB
o KEYCODE_UP

____________


ΓòÉΓòÉΓòÉ 15.6.2. ascii_keymap ΓòÉΓòÉΓòÉ

ascii_keymap  read-only   Primitive

Purpose: Predefined keyboard of just the ASCII character keys.

____________

Type:   keymapid ascii_keymap

____________

Description:

The ascii_keymap variable stores the id of a keymap which has only the keys
corresponding to ASCII values defined. In this keymap, keys which return an
ASCII value (1 to 255) are bound to the insert_key() function.  That is, they
insert that character in the buffer.  This is the extent of the key
definitions.  Key sequences such as [Alt][X] or [F1] will have no corresponding
function with this keyboard definition.  The key, however, functions
independently of any keymap and is therefore always defined.

This variable is primarily used when creating a new keymap.  Used as an
argument to the create_keymap() function, ascii_keymap provides a method of
initializing a new keymap to a minimally useful definition.  You may then build
upon this definition as you please.

This variable serves as a constant value and may not be modified by the user.

____________

See also:  factory_keymap, empty_keymap


ΓòÉΓòÉΓòÉ 15.6.3. buffer_keymap ΓòÉΓòÉΓòÉ

buffer_keymap   Primitive

Purpose: Identifies keymap that locally overlays current default.

____________

Type:   keymapid buffer_keymap

____________

Description:

Each buffer has a buffer_keymap variable associated with it.  The buffer_keymap
contains the keymap id of a keyboard definition intended to replace a portion
or all of the current_keymap definition.

This local keyboard definition will only apply to the buffer in which the
assignment is made.  Any keystrokes which have not been defined by the local
keyboard definition will be handled by the keymap described by the
current_keymap variable.


ΓòÉΓòÉΓòÉ 15.6.4. current_keymap ΓòÉΓòÉΓòÉ

current_keymap   Primitive

Purpose: Stores the id of the keymap presently in use.

____________

Type: keymapid current_keymap

____________

Description:

The current_keymap variable contains the keymap id of the keyboard definition
currently in use.  This is the keymap in effect regardless of which buffer is
currently being edited.  The keymap currently in use may be changed by
assigning a new value to this variable.  If an invalid keymap id is assigned to
current_keymap, the assignment will have no effect.

The actual key assignments in effect may also be influenced by another keymap
which overlays the one indicated by this variable.  These keymaps used as
overlays are local in that they only apply to a specific buffer.  The
buffer_keymap variable indicates when a keymap has been overlaid by another.

During the construction of a new keymap it is common to assign an blank
keyboard definition (empty_keymap) to current_keymap and then add key
assignments.  If, however, the editor is allowed to proceed using an empty
keymap the editor will become unusable.

____________

See also:  ascii_keymap, empty_keymap, factory_keymap


ΓòÉΓòÉΓòÉ 15.6.5. default_key_action ΓòÉΓòÉΓòÉ

default_key_action   Primitive

Purpose: Specifies function to be executed if a key is not assigned in the
current keymap.

____________

Type:   funcid default_key_action

____________

Description:

The default_key_action variable contains the function id of the function to run
if the key pressed is not defined in the current keymap.  If this variable is
not set then the beep() function is called when a non-mapped key is pressed.
The example below illustrates how to pop up a warning box everytime a key is
pressed that is not in the currently loaded keymap.


ΓòÉΓòÉΓòÉ 15.6.6. empty_keymap ΓòÉΓòÉΓòÉ

empty_keymap  read-only   Primitive

Purpose: Stores id of keyboard definition with no assignments.

____________

Type:   keymapid empty_keymap

____________

Description:

The empty_keymap variable stores the keymap id number of a predefined keymap
which contains no functions assigned to any of the keys.  Typing exit commands
or even simple characters is ineffective with this keyboard definition.

This variable is primarily used when creating a new keymap.  Used as an
argument to the create_keymap() function, empty_keymap provides a method of
building a keymap from scratch.  There are other predefined keymaps that allow
you to build upon or modify a more substantial keyboard definition.

This variable serves as a constant value and may not be modified by the user.

____________

See also:  factory_keymap, ascii_keymap


ΓòÉΓòÉΓòÉ 15.6.7. factory_keymap ΓòÉΓòÉΓòÉ

factory_keymap read-only   Primitive

Purpose: Predefined keyboard of standard editor keys.

____________

Type:   keymapid factory_keymap

____________

Description:

The factory_keymap variable stores the id of a keymap containing the minimal
editor key assignments.  This is the keymap that is put in effect when
operating the editor without its function library. Do not confuse this keymap
with the keymap defined in the native() function.

This variable is primarily used when creating a new keymap.  Used as an
argument to the create_keymap() function, factory_keymap provides a method of
initializing a new keymap to the standard definition.  You may then modify its
definition to suit.

factory_keymap is a constant value and may not be modified by the user.

____________

See also:  empty_keymap, ascii_keymap


ΓòÉΓòÉΓòÉ 15.6.8. playingback ΓòÉΓòÉΓòÉ

playingback   PEL

Purpose:  Indicates whether a keyboard macro is being played back.

____________

Type:    int playingback

____________

Description: The playingback variable stores a value (either TRUE or FALSE),
indicating whether a keyboard macro is being played.  If it is TRUE, a macro is
being played, otherwise a macro is not being played.

____________


ΓòÉΓòÉΓòÉ 15.6.9. recording ΓòÉΓòÉΓòÉ

recording   PEL

Purpose:  Indicates whether a keyboard macro is being recorded back.

____________

Type:    int recording

____________

Description: The recording variable stores a value (either TRUE or FALSE),
indicating whether a keyboard macro is being recorded.  If it is TRUE, a macro
is being recorded, otherwise a macro is not being recorded.

____________


ΓòÉΓòÉΓòÉ 15.6.10. window_keymap ΓòÉΓòÉΓòÉ

window_keymap   Primitive

Purpose: Identifies the keymap that locally overlays the current default.

____________

Type: keymapid window_keymap

____________

Description: Each window has an associated window_keymap variable.  The
window_keymap variable contains the keymapid of a keyboard definition intended
to replace a portion or all of the current_keymap definition. This local
keyboard definition only applies to the window in which the assignment is made.
Any keystrokes which have not been defined by the local keyboard definition
will be handled by the keymap described by the current_keymap variable.

____________

See also: current_keymap, buffer_keymap


ΓòÉΓòÉΓòÉ 15.7. Menus ΓòÉΓòÉΓòÉ

IDM_
          Menu item constants.
MI_
          Constants for menu item flags.
POP_
          Constants for the pop up menu items.


ΓòÉΓòÉΓòÉ 15.7.1. IDM_ ΓòÉΓòÉΓòÉ

IDM_   PEL

Purpose:  Menu item constants.

____________

Type:    const int IDM_

____________

Description: The IDM_ constants are used when performing functions in the menus
category.  They provide an easy method to specify the menu item the calling
fuction will affect.

o IDM_ABOUT
o IDM_ADDFILE
o IDM_ARRANGE_ICONS
o IDM_ARRANGE_WINDOW
o IDM_BOOKMARK
o IDM_BOOKMARKLIST
o IDM_BUFFERLIST
o IDM_BUFFERS
o IDM_BUFFER_MASK
o IDM_BUFFER_SETTINGS
o IDM_CASCADE_BUFFERS
o IDM_CASCADE_WINDOW
o IDM_CHANGE
o IDM_CLOSE
o IDM_CLOSE_ALL_WINDOWS
o IDM_CLOSE_WINDOW
o IDM_COLOR
o IDM_COMMAND
o IDM_COMPILE
o IDM_COPY
o IDM_CTAGS_LOCATE
o IDM_CTAGS_MAKE
o IDM_CUT
o IDM_DELETE
o IDM_DIALOG_LIST
o IDM_DOSBOX
o IDM_DOSSHELL
o IDM_EDIT
o IDM_EDITOR_SETTINGS
o IDM_ERRORFILE
o IDM_EXIT
o IDM_FILE
o IDM_FIND
o IDM_FINDAGAIN
o IDM_FINDMATCHING
o IDM_FONT
o IDM_GENERAL
o IDM_GET
o IDM_GOTOLINE
o IDM_HELP
o IDM_HSPLIT_WINDOW
o IDM_INDENT
o IDM_INDEX
o IDM_INSERTFILE
o IDM_ISEARCH
o IDM_KEYWORDHELP
o IDM_KEY_BINDINGS
o IDM_LOWER
o IDM_MARKMATCHING
o IDM_MARKNEXTMATCHING
o IDM_NAVIGATE
o IDM_NEW
o IDM_NEW_WINDOW
o IDM_NEXT
o IDM_NEXTERR
o IDM_NEXT_WINDOW
o IDM_OPENCLOSE
o IDM_OPTIONS
o IDM_OUTDENT
o IDM_PASTE
o IDM_PELTAGS_MAKE
o IDM_PEL_DEBUGGER
o IDM_PREV
o IDM_PREVERR
o IDM_PREV_WINDOW
o IDM_PRINT
o IDM_PRINTSEL
o IDM_PUT
o IDM_PVCS
o IDM_REDO
o IDM_ROUTINE
o IDM_SAVE
o IDM_SAVEALL
o IDM_SAVEAS
o IDM_SAVE_SETTINGS
o IDM_SAVE_STATE
o IDM_SEARCH
o IDM_STATUSBAR
o IDM_TAGS
o IDM_TILE_BUFFERS
o IDM_TILE_WINDOW
o IDM_TOGGLE_LINENUMBER
o IDM_TOGGLE_SCROLLBARS
o IDM_TOOLBAR
o IDM_TOOLS
o IDM_UNDER_CURSOR
o IDM_UNDO
o IDM_UPPER
o IDM_USING
o IDM_VCS
o IDM_VDIFF
o IDM_VLOG
o IDM_VSPLIT_WINDOW
o IDM_WINDOW
o IDM_WINDOW_MODE
o IDM_WINDOW_SETTINGS
o IDM_XANALYZER
o IDM_XBATCHDEBUGGER
o IDM_XCICSDEBUGGER
o IDM_XCOBOL_OPTIONS
o IDM_XCOMPILER
o IDM_XEDITANOTHER
o IDM_XRETROFIT
o IDM_XSYNTAX

____________


ΓòÉΓòÉΓòÉ 15.7.2. MI_ ΓòÉΓòÉΓòÉ

MI_   PEL

Purpose:  Constants for menu item flags.

____________

Type:    const int MI_

____________

Description: The constants defined in the MI_ section con be used as flags to
functions like modify_menuitem().

o MI_CHECKED
o MI_DEFAULT
o MI_DISABLED
o MI_ENABLED
o MI_FUNCTIONID
o MI_HELPID
o MI_HELPTEXT
o MI_ITEMCOUNT
o MI_ITEMTEXT
o MI_MENUBREAK
o MI_MENUHANDLE
o MI_MENUITEM
o MI_SEPARATOR
o MI_SUBDEFAULT
o MI_SUBMENU
o MI_UNCHECKED

____________


ΓòÉΓòÉΓòÉ 15.7.3. POP_ ΓòÉΓòÉΓòÉ

POP_   PEL

Purpose:  Constants for the pop up menu items.

____________

Type:    const int POP_

____________

Description: The constants defined in the POP_ section are used to modify the
popup menu items with functions like modify_menuitem().

o POP_COPY
o POP_CUT
o POP_DELETE
o POP_FIND
o POP_FINDMATCHING
o POP_INDENT
o POP_INSERTFILE
o POP_KEYWORDHELP
o POP_LOWER
o POP_MARKMATCHING
o POP_MARKNEXTMATCHING
o POP_MENU_START
o POP_OUTDENT
o POP_PASTE
o POP_UPPER
o POP_WRITEBLOCK

____________


ΓòÉΓòÉΓòÉ 15.8. Miscellaneous ΓòÉΓòÉΓòÉ

FONT_
Font name constants.
backup_file_ext
          Names extension applied to backup files.
color_error_bg
          Defines background color used to draw text.
color_error_fg
          Defines foreground color used to draw text.
color_help_bg
          Defines background color used to draw help text.
color_help_fg
          Defines foreground color used to draw text.
create_new_bufwin
          Indicator of one buffer per window mode.
currentRecordString
          Holds the current keyboard macro string.
debugger_running
          Indicates whether the PEL debugger is running.
dropped_file
          Contains the name of the file(s) that were dragged and dropped onto
          the editor.
extension_array
          Store information specific to an extension
linenumber_format
          Determines if and how line numbers are displayed.
linenumber_width
          Store the width of the linenumber field
matching_pairs
          Stores the list of matching pairs for the current buffer
message_level
          Indicates to what degree of messages should be displayed.
print_device
          Stores device or file name used for printing.
process_id
          Contains the process id of a background process.
process_rc
          Contains the return code of a background process.
screen_height()
          Height of the entire screen in pixels.
screen_width()
          Width of the entire screen in pixels.
section_pattern
          Define what delimits a section.
status_bar_flags
          Indicates what appears on the status bar
text_char_height
          Store the height of text characters.
text_char_width
          Store the width of text characters.


ΓòÉΓòÉΓòÉ 15.8.1. FONT_ ΓòÉΓòÉΓòÉ

FONT_   PEL

Purpose:  Font name constants.

____________

Type:    const int FONT_

____________

Description: The constants defined int the FONT_ section can be used to set the
editor font.

o FONT_ANY
o FONT_BOLD
o FONT_DECORATIVE
o FONT_FIXEDPITCH
o FONT_ITALIC
o FONT_LIGHT
o FONT_MODERN
o FONT_MODERN10
o FONT_MODERN12
o FONT_MODERN8
o FONT_NONE
o FONT_NORMAL
o FONT_ROMAN
o FONT_SCRIPT
o FONT_STRIKETHRU
o FONT_SWISS
o FONT_UNDERLINE

____________


ΓòÉΓòÉΓòÉ 15.8.2. backup_file_ext ΓòÉΓòÉΓòÉ

backup_file_ext   PEL

Purpose: Names extension applied to backup files.

____________

Type:   str backup_file_ext

____________

Description:

The backup_file_ext variable specifies the extension with which backup files
are identified.  This variable may optionally contain a leading dot or period.
The default value of this variable is an empty string, which implies that the
extension is not changed.  A single asterisk, "*", may also be used to signify
that the extension is not changed.

The variable backup_directory determines where the backup file will be created.
The backup directory may be specified as, or through error become, the same
directory as the file being edited.  When this occurs and no backup_file_ext
has been specified, the extension ".BAK" is used to avoid overwriting the
original file.

____________

See also:  backup_directory


ΓòÉΓòÉΓòÉ 15.8.3. color_error_bg ΓòÉΓòÉΓòÉ

color_error_bg   Primitive

Purpose: Defines background color used to draw text.

____________

Type: int color_error_bg

____________

Description:

Each editor window has a color_error_bg variable associated with it.  This
variable contains the background color of error text when errors are displayed
on the status bar.

The initial value is copied from the global variable default_color_error_bg.

____________

See also:  error(), color_message_fg, color_message_fg, color_notify_fg,
color_notify_fg, color_warning_fg, color_warning_fg, color_error_fg


ΓòÉΓòÉΓòÉ 15.8.4. color_error_fg ΓòÉΓòÉΓòÉ

color_error_fg   Primitive

Purpose: Defines foreground color used to draw text.

____________

Type: int color_error_fg

____________

Description:

Each editor window has a color_error_fg variable associated with it.  This
variable contains the foreground color of error text when errors are displayed
on the status bar.

The initial value is copied from the global variable default_color_error_fg.

____________

See also:   error(), color_message_bg, color_message_fg, color_notify_bg,
color_notify_fg, color_warning_bg, color_warning_fg, color_error_bg


ΓòÉΓòÉΓòÉ 15.8.5. create_new_bufwin ΓòÉΓòÉΓòÉ

create_new_bufwin   Primitive

Purpose:  Indicator of one buffer per window mode.

____________

Type:    int create_new_bufwin

____________

Description: The create_new_bufwin variable indicates whether the editor is in
one buffer per window mode.

____________

See also:

o create_buf_and_win()


ΓòÉΓòÉΓòÉ 15.8.6. currentRecordString ΓòÉΓòÉΓòÉ

currentRecordString   PEL

Purpose:  Holds the current keyboard macro string.

____________

Type:    str currentRecordString

____________

Description: The currentRecordString is the string used to record keystrokes
for a keyboard macro.  The commands are stored in this string for later use in
a playback() function.

____________


ΓòÉΓòÉΓòÉ 15.8.7. debugger_running ΓòÉΓòÉΓòÉ

debugger_running   PEL

Purpose:  Indicates whether the PEL debugger is running.

____________

Type:    int debugger_running

____________

Description: The debugger_running variable stores a value (either TRUE or
FALSE), indicating whether the PEL debugger is currently running.  If it is
TRUE, the debugger is running, otherwise a the debugger is not running.

____________


ΓòÉΓòÉΓòÉ 15.8.8. default_ ΓòÉΓòÉΓòÉ

default_   PEL

Purpose: Defines initial value of window or buffer variable.

____________

Type:

o str default_buffer_eof_string
o str default_buffer_eol_string
o int default_buffer_flags
o str default_buffer_tabs
o str default_linenumber_format
o int default_scroll_context_bottom
o int default_scroll_context_left
o int default_scroll_context_right
o int default_scroll_context_top
o int default_scroll_means_pan
o int default_scroll_unit_horizontal
o int default_scroll_unit_vertical
o str default_visible_end_buffer
o str default_visible_newlines
o str default_visible_spaces
o str default_visible_tabs
o str default_visible_virtual_lines
o str default_visible_virtual_spaces
o int default_window_flags
o int default_window_page_offset
o int default_window_page_overlap
o int default_wp_left_margin
o int default_wp_right_margin

____________

Description: Each buffer or window has a series of variables associated with
it.  These are variables that may require different values for different
buffers.  For example, one buffer may require tab stops at every four columns
while another requires them at every eight. This series of variables obtain
their initial value from another global set of variables at the time the buffer
or window is created.  These special variables are the default_ series of
variables.

The global variable corresponding to the buffer or window variable has the same
name as the buffer or window variable but prefixed by default_.  The value of
the global variable is copied into like-named variable at the time the buffer
is created. This local variable is then an attribute of the buffer or window.

For example, each buffer has a buffer_tabs variable associated with it.  Each
buffer_tabs variable derives its initial value from the single global variable
named default_buffer_tabs.  After the buffer has been created, the buffer_tabs
variable may be accessed or changed whenever that buffer is current.  The value
of the variable default_buffer_tabs may be changed at any time, but the new
value is only used by buffers subsequently created.

The default values for the default_ buffer variables are as follows:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariable name                 ΓöéValue     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_buffer_eof_string     Γöé""        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_buffer_eol_string     Γöé"\r\n"    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_buffer_flags          Γöés 0       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_buffer_tabs           Γöé"9  17"   Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_wp_left_margin        Γöé1         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_wp_right_margin       Γöé77        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
 The default values for the default_ window variables are as follows:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéVariable name                 ΓöéValue     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_linenumber_format     Γöé""        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_means_pan      Γöé1         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_end_buffer    Γöé""        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_newlines      Γöé""        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_spaces        Γöé" "       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_tabs          Γöé" "       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_virtual_lines Γöé""        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_visible_virtual_spacesΓöé" "       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_context_bottom Γöé0         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_context_left   Γöé0         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_context_right  Γöé0         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_context_top    Γöé0         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_unit_horizontalΓöé1         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_scroll_unit_vertical  Γöé1         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_window_flags          Γöé0x1091    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_window_page_offset    Γöé0         Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöédefault_window_page_overlap   Γöé1         Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.8.9. default_matching_pairs ΓòÉΓòÉΓòÉ

default_matching_pairs   PEL

Purpose:  Stores the default list of matching pairs.

____________

Type:    str default_matching_pairs

____________

Description: The default_matching_pairs variable is the default list of symbols
that are considered matching pairs.  The matching_pairs variable is used when
the goto_matching() function is called.  If the matching_pairs has not been set
for an extension, the default_matching_pairs variable is used instead.

____________


ΓòÉΓòÉΓòÉ 15.8.10. dropped_file ΓòÉΓòÉΓòÉ

dropped_file  Read-Only   Primitive

Purpose: Contains the name of the file(s) that were dragged and dropped onto
the editor.

____________

Type:   str dropped_file

____________

Description:

This variable is set when a file or files is dropped onto a running editor.
The EVENT.FILE_DROPPED event is generated when a file is dropped on the editor.


ΓòÉΓòÉΓòÉ 15.8.11. extension_array ΓòÉΓòÉΓòÉ

extension_array   PEL

Purpose:  Store information specific to an extension

____________

Type:    pelarray extension_array

____________

Description: The extension_array stores information that is specific to a an
extension.  Information in the array includes: tab stops, margins,
matching_pairs, and word wrap.  These settings are stored in the editor
configuration file and can be set in the settings notebook on the extensions
page.

____________


ΓòÉΓòÉΓòÉ 15.8.12. linenumber_format ΓòÉΓòÉΓòÉ

linenumber_format   Primitive

Purpose: Determines if and how line numbers are displayed.

____________

Type: str linenumber_format

____________

Description: Each window has a linenumber_format variable associated with it.
The linenumber_format variable stores a format string used in displaying line
numbers.  The rules for interpreting the format string are largely a subset of
those used by fprintf().  This string, after formatting, is displayed to the
left of each line of text.

This string may be empty, in which case line numbers are turned off.  When line
numbers are to be displayed this string will follow the form below:

    [leading_text]%[[0]n]c[trailing_text]

Where leading_text and trailing_text are strings you wish to have precede and
follow each line number, n is the number of columns allotted to line numbers
and c is a format character indicating the numeric base to be used.  The
leading_text may not contain a percent sign.  Values allowed for n are 1 to 9.
If the line number would occupy more than the specified number of columns the
most significant digits are not displayed.  The optional 0 preceding n
specifies that the number is left- filled with zeros rather than spaces.
Values for c are shown below:

Format Char    Description
b              binary notation
d              decimal notation
o              octal notation
x              hexadecimal notation
X              hexadecimal, letters are upper case

The format string will normally contain a percent sign, a number, a format
character and a character to separate line numbers from the beginning of text.
An example is shown below:

   linenumber_format = "%4d:""

This variable takes its initial value at the time the window is created from
the variable default_linenumber_format.  The initial value of that variable is
" ".  Invalid formats are treated the same as " ".

____________

See also:   color_linenumbers_fg,color_linenumbers_bg


ΓòÉΓòÉΓòÉ 15.8.13. linenumber_width ΓòÉΓòÉΓòÉ

linenumber_width   Primitive

Purpose:  Store the width of the linenumber field

____________

Type:    int linenumber_width

____________

Description: The linenumber_width variable stores the width of the linenumber
field in characters.

____________

See also: linenumber_format


ΓòÉΓòÉΓòÉ 15.8.14. matching_pairs ΓòÉΓòÉΓòÉ

matching_pairs   PEL

Purpose:  Stores the list of matching pairs for the current buffer

____________

Type:    str matching_pairs

____________

Description: The matching_pairs variable is the list of symbols that are
considered matching pairs.  It is used when the goto_matching() function is
called.  The matching_pairs variable can be set per file extension on the
extensions page of the settings notebook.

____________


ΓòÉΓòÉΓòÉ 15.8.15. message_level ΓòÉΓòÉΓòÉ

message_level   Primitive

Purpose: Indicates to what degree of messages should be displayed.

____________

Type: int message_level

____________

Description: The message_level variable allows the user to limit, to varying
degrees, messages from the editor system or macros.  These are the messages
displayed by the functions message(), warning(), notify() and error() as well
as internal messages.  They appear in a message box or on the status bar.

The useful values for this variable are shown below, along with their meaning:

Level     Description
0         All messages are displayed.
1         Suppress message() output.
2         Display only warning() and error().
3         No messages displayed.

If other values are assigned to this variable, all messages will be printed.
The default value for this variable is 1.

____________

See also:   message(), notify(), warning(), error()


ΓòÉΓòÉΓòÉ 15.8.16. print_device ΓòÉΓòÉΓòÉ

print_device   Primitive

Purpose: Stores device or file name used for printing.

____________

Type: str print_device

____________

Description: The print_device string names the device to which the
print_buffer() function will write.  Its default value is "prn".  It may be set
to such values as "lpt2" or "myfile.txt" as desired.


ΓòÉΓòÉΓòÉ 15.8.17. process_id ΓòÉΓòÉΓòÉ

process_id   Primitive

Purpose:  Contains the process id of a background process.

____________

Type:    Read-Only long

____________

Description: The process_id variable stores the process id of the most recently
completed background process or the process that generated some pipe data.  See
the system function on how to start a background process. When a background
process is complete an EVENT.PROCESS_COMPLETE event is generated.  When pipe
data is available an EVENT.PIPE_DATA event is generated,  This variable may
only be modified by the system.


ΓòÉΓòÉΓòÉ 15.8.18. process_rc ΓòÉΓòÉΓòÉ

process_rc   Primitive

Purpose:  Contains the return code of a background process.

____________

Type:    Read-Only long

____________

Description: The process_rc variable stores the return code of the most
recently completed background process.  See the system function on how to start
a background process.  When a background process is complete an
EVENT.PROCESS_COMPLETE event is generated.  This variable may only be modified
by the system.


ΓòÉΓòÉΓòÉ 15.8.19. screen_height ΓòÉΓòÉΓòÉ

screen_height  Read-Only   Primitive

Purpose: Height of the entire screen in pixels.

____________

Type:   str screen_height

____________

Description:

The screen_height variable contains the height of the entire display screen in
pixels.


ΓòÉΓòÉΓòÉ 15.8.20. screen_width ΓòÉΓòÉΓòÉ

screen_width  Read-Only   Primitive

Purpose: Width of the entire screen in pixels.

____________

Type:   str screen_width

____________

Description:

The screen_width variable contains the width of the entire display screen in
pixels.


ΓòÉΓòÉΓòÉ 15.8.21. section_pattern ΓòÉΓòÉΓòÉ

section_pattern   PEL

Purpose:  Define what delimits a section.

____________

Type:    str section_pattern

____________

Description: The section_pattern variable defines what delimits a section. This
variable is used in the section motion functions.

____________


ΓòÉΓòÉΓòÉ 15.8.22. status_bar_flags ΓòÉΓòÉΓòÉ

status_bar_flags   Primitive

Purpose:  Indicates what appears on the status bar

____________

Type:    int status_bar_flags

____________

Description: The status_bar_flags variable is analagous to the buffer_flags
variable.  It holds the current state of the status bar and what is displayed
there.  The flags may be set on the status bar page of the settings notebook.
To help set or check the flags manually there are several status bar flag
masks. The masks are listed in the STB_ section.

____________


ΓòÉΓòÉΓòÉ 15.8.23. text_char_height ΓòÉΓòÉΓòÉ

text_char_height   Primitive

Purpose:  Store the height of text characters.

____________

Type:    int text_char_height

____________

Description: The text_char_height stores the height of text characters in
pixels. This variable is changed when the font changes.

____________


ΓòÉΓòÉΓòÉ 15.8.24. text_char_width ΓòÉΓòÉΓòÉ

text_char_width   Primitive

Purpose:  Store the width of text characters.

____________

Type:    int text_char_width

____________

Description: The text_char_width stores the width of text characters in pixels.
This variable is changed when the font changes.

____________


ΓòÉΓòÉΓòÉ 15.9. Motion ΓòÉΓòÉΓòÉ

scroll_context_bottom
          Scrolling margin honored by cursor at screen bottom.
scroll_context_left
          Scrolling margin honored by cursor at screen left.
scroll_context_right
          Scrolling margin honored by cursor at screen right.
scroll_context_top
          Scrolling margin honored by cursor at screen top.
scroll_means_pan
          Indicates whether movements apply to cursor or text.
scroll_unit_horizontal
          Stores number of columns in horizontal scrolling unit.
scroll_unit_vertical
          Stores the number of lines in vertical scrolling unit.


ΓòÉΓòÉΓòÉ 15.9.1. scroll_context_bottom ΓòÉΓòÉΓòÉ

scroll_context_bottom   Primitive

Purpose: Scrolling margin honored by cursor at screen bottom.

____________

Type: int scroll_context_bottom

____________

Description: Each window has a scroll_context_bottom variable associated with
it.  The value stored in scroll_context_bottom is used to determine when to
scroll the contents of the edit window upward.  The editor will keep at least
this number of lines between the cursor and the bottom border of the window.

When actions would otherwise place the cursor less than the number of lines
indicated by scroll_context_bottom from the border, the window is scrolled to
compensate.

This is used to provide a definable amount of context around the area where
text modifications are taking place.

The scroll_context_bottom variable takes its initial value from the
default_scroll_context_bottom at the time the window is created.  Assigning a
value less than zero to this variable is treated the same as zero.

____________

See also:   scroll_context_left, scroll_context_right, scroll_context_top


ΓòÉΓòÉΓòÉ 15.9.2. scroll_context_left ΓòÉΓòÉΓòÉ

scroll_context_left   Primitive

Purpose: Scrolling margin honored by cursor at screen left.

____________

Type: int scroll_context_left

____________

Description: Each window has a scroll_context_left variable associated with it.
The value stored in scroll_context_left is used to determine when to scroll the
contents of the edit window to the right.  The editor will attempt to keep at
least this number of columns between the cursor and the left border of the
window.

When actions would otherwise place the cursor less than the number of columns
indicated by scroll_context_left from the border, the window is scrolled to
compensate.

The exception to this action is when the text is already scrolled all the way
to the right.  In this case, the cursor may be moved to the edge of the window.

This is used to provide a definable amount of context around the area where
text modifications are taking place.

The scroll_context_left variable takes its initial value from the
default_scroll_context_left at the time the window is created.  Assigning a
value less than zero to this variable is treated the same as zero.

____________

See also:   scroll_context_bottom, scroll_context_right, scroll_context_top


ΓòÉΓòÉΓòÉ 15.9.3. scroll_context_right ΓòÉΓòÉΓòÉ

scroll_context_right   Primitive

Purpose: Scrolling margin honored by cursor at screen right.

____________

Type: int scroll_context_right

____________

Description: Each window has a scroll_context_right variable associated with
it.  The value stored in scroll_context_right is used to determine when to
scroll the contents of the edit window to the left. The editor will keep at
least this number of columns between the cursor and the right border of the
window.

When actions would otherwise place the cursor less than the number of columns
indicated by scroll_context_right from the border, the window is scrolled to
compensate.

This is used to provide a definable amount of context around the area where
text modifications are taking place.

The scroll_context_right variable takes its initial value from the
default_scroll_context_right at the time the window is created.  Assigning a
value less than zero to this variable is treated the same as zero.

____________

See also:   scroll_context_left, scroll_context_bottom, scroll_context_top


ΓòÉΓòÉΓòÉ 15.9.4. scroll_context_top ΓòÉΓòÉΓòÉ

scroll_context_top   Primitive

Purpose: Scrolling margin honored by cursor at screen top.

____________

Type: int scroll_context_top

____________

Description: Each window has a scroll_context_top variable associated with it.
The value stored in scroll_context_top is used to determine when to scroll the
contents of the edit window down.  The editor will keep at least this number of
lines between the cursor and the top border of the window.

When actions would otherwise place the cursor less than the number of columns
indicated by scroll_context_top from the border, the window is scrolled to
compensate.

The exception to this action is when the text is already scrolled to the top of
the buffer.  In this case, the cursor may be moved to the top edge of the
window.

This variable is used to provide a defined amount of context around the area
where text modifications are taking place.

The scroll_context_top variable takes its initial value from the
default_scroll_context_top at the time the window is created.  Assigning a
value less than zero to this variable is treated the same as zero.

____________

See also:   scroll_context_left, scroll_context_bottom, scroll_context_right


ΓòÉΓòÉΓòÉ 15.9.5. scroll_means_pan ΓòÉΓòÉΓòÉ

scroll_means_pan   Primitive

Purpose: Indicates whether movements apply to cursor or text.

____________

Type: int scroll_means_pan

____________

Description: Each window has a scroll_means_pan variable associated with it.
When this variable is set to zero, cursor and other operations generally have
the effect of moving the cursor in relationship to the window.

When scroll_means_pan is other than zero, the position of the cursor within the
window is preserved.  The text in the window moves to compensate.

Typing with the editor in this mode may remind you of how the typing ball on
many typewriters stays in one place while the carriage moves by.  Scrolling
text up and down, on the other hand, may remind you of an airplane simulator.

Another way of looking at it is as follows:  When scroll_means_pan is 0, The
editor attempts to preserve the cursor position relative to its location in the
buffer.  When scroll_means_pan is 1, the editor preserves the cursor position
relative to the window.

The scroll_means_pan variable takes its initial value from the
default_scroll_means_pan at the time the window is created.

The Scroll Lock key is used by the higher level scroll functions to complement
the value of scroll_means_pan.  This has the effect of reversing the sense of
scroll_means_pan.  When Scroll Lock is toggled on, functions that use
scroll_means_pan will complement its value before using it.  When Scroll Lock
is off the uncomplemented value is used.

____________

See also:   scroll_horizontal(), scroll_vertical(), page_up(), page_down()


ΓòÉΓòÉΓòÉ 15.9.6. scroll_unit_horizontal ΓòÉΓòÉΓòÉ

scroll_unit_horizontal   Primitive

Purpose: Stores number of columns in horizontal scrolling unit.

____________

Type: int scroll_unit_horizontal

____________

Description: Each window has a scroll_unit_horizontal variable associated with
it.  The scroll_unit_horizontal variable defines the number of columns in the
normal scrolling unit for horizontal movement. This variable comes into play
when cursor motion causes the contents of a window to be scrolled horizontally.

The default value for this variable is usually 1. This means that when cursor
movement causes the text in a window is scrolled to the left or right, one
off-window column of text appears in the window.  This is the method of
operation most users will find familiar.

When higher values are assigned to scroll_unit_horizontal, more than one
off-window column of text becomes visible during a single scroll.  This has the
effect of reducing the number of times the text needs to be scrolled.  As a
result, continued cursor movements may often be executed more quickly.

The size of the scrolling unit does not change the way the cursor moves through
the text.  In the following example, imagine that the scroll_unit_horizontal
variable is set to 5.  (To keep things simple we will also assume that
scroll_context_right is set to its default value, zero.)  The cursor is
positioned at the right edge of the window on the letter "G", which happen to
be the first letter of the word "GetShape".

When the cursor-right key is pressed, five off-window columns of text are
scrolled into the window.  Now, only the final "pe" of "GetShape" is not
visible.  The cursor, however, is no longer at the right edge of the window.
The cursor has moved from the first character of "GetShape" to the second.
This leaves four columns between the cursor and the window edge.

The scroll_unit_horizontal variable takes its initial value from the
default_scroll_unit_horizontal at the time the window is created.  Values of
less than 1 are interpreted as 1.  Values greater than the window width are
interpreted as the width of the window.

____________

See also:   scroll_unit_vertical


ΓòÉΓòÉΓòÉ 15.9.7. scroll_unit_vertical ΓòÉΓòÉΓòÉ

scroll_unit_vertical   Primitive

Purpose: Stores the number of lines in vertical scrolling unit.

____________

Type: int scroll_unit_vertical

____________

Description: Each window has a scroll_unit_vertical variable associated with
it.  the scroll_unit_vertical variable defines the number of lines  in the
normal scrolling unit for vertical movement.  This variable comes into play
when cursor motion causes the contents of a window to be scrolled vertically.

The default value for this variable is usually 1. This means that when, as the
result of cursor movement the text in a window is scrolled up or down, one
off-window line of text appears in the window.  This is the method of operation
most users will find familiar.

When higher values are assigned to scroll_unit_vertical, more than one
off-window line of text becomes visible during a single scroll. This has the
effect of reducing the number of times the text needs to be scrolled.  As a
result, continuing cursor movements may often be executed more quickly.

The size of the scrolling unit does not change the way the cursor moves through
the text.  Though several new lines are made to appear on the screen at once,
the up and down cursor keys will always move the cursor to the adjacent line of
text.

The scroll_unit_vertical variable takes its initial value from the
default_scroll_unit_vertical at the time the window is created.  Values of less
than 1 are interpreted as 1.  Values greater than the window height are
interpreted as the height of the window.

____________

See also:   scroll_unit_horizontal


ΓòÉΓòÉΓòÉ 15.10. Notebook ΓòÉΓòÉΓòÉ

NBTAB_
Notebook tab constants.


ΓòÉΓòÉΓòÉ 15.10.1. NBTAB_ ΓòÉΓòÉΓòÉ

NBTAB_   Primitive

Purpose:  Notebook tab constants.

____________

Type:    const int NBTAB_

____________ Dscription: The constants defined in the NBTAB_ section are used
as flags to the set_notebook_tab_type() function.

o NBTAB_BOTTOM
o NBTAB_LEFT
o NBTAB_MAJOR
o NBTAB_MINOR
o NBTAB_NONE
o NBTAB_POLYGON
o NBTAB_RIGHT
o NBTAB_ROUNDED
o NBTAB_SQUARE
o NBTAB_TOP

____________


ΓòÉΓòÉΓòÉ 15.11. PEL Programming ΓòÉΓòÉΓòÉ

ARGC
          Stores the number of arguments in editor invocation
ARGV
          Stores the command line used to invoke the editor.
electric_mode
          Flag used to indicate if the edior had template expansion turned on.
ENV
          Stores the values of environment variables.
FS()
          Identifies the default AWK input field separator.
language_template[]
          Store the curent template definition.
OFS
          Identifies the AWK output field separator.
ORS
          Identifies the AWK output record separator.
SUBSEP
          Sets string used to simulate multidimensional arrays.
tags_path
          Path the editor uses to find tags files


ΓòÉΓòÉΓòÉ 15.11.1. ARGC ΓòÉΓòÉΓòÉ

ARGC   Primitive

Purpose: Stores the number of arguments in editor invocation

____________

Type:   int ARGC

____________

Description:

On start-up, the editor sets this variable to the number of parameters
specified on the command line when the editor was invoked. This value
represents the number of elements of the ARGV array and is always at least one,
since the editor invocation name itself is counted.

The value of ARGC may be modified by the startup() function, but this should
only be done to reflect parallel changes to the ARGV array.

____________

See also:   ARGV


ΓòÉΓòÉΓòÉ 15.11.2. ARGV ΓòÉΓòÉΓòÉ

ARGV   Primitive

Purpose: Stores the command line used to invoke the editor.

____________

Type:   array ARGV

____________

Description:

The AWK array ARGV contains all of the elements of the command line used to
invoke the current session of the editor.  Elements are separated on the basis
of whitespace.  It may be examined or modified at any time. Each element of the
array is a series of characters in the original command line which were
surrounded by whitespace.

If ARGV is modified by the startup() function, the modified ARGV will be
processed as if it had been entered on the DOS command line.  When received
from DOS, ARGV will contain a total of up to 128 significant characters.  It
may, however, be safely modified to be much larger, if desired.  When this
array is modified, however, it is advisable to modify the ARGC variable to
reflect the new number of arguments.  The first element of this array is the
editor invocation name.

____________

Example:

ARGV[0] == "p"


ΓòÉΓòÉΓòÉ 15.11.3. electric_mode ΓòÉΓòÉΓòÉ

electric_mode   PEL

Purpose:  Flag used to indicate if the edior had template expansion turned on.

____________

Type:    int electric_mode

____________

Description: The electric_mode variable, if TRUE, indicates that the editor had
template expansion turned on.  This allows the user to take advantage of the
built in shortcut keys for coding.

____________

See also:

o languages[]
o get_expand_template()


ΓòÉΓòÉΓòÉ 15.11.4. ENV ΓòÉΓòÉΓòÉ

ENV   Primitive

Purpose: Stores the values of environment variables.

____________

Type:   array ENV

____________

Description:

The ENV variable is an AWK array containing the values found in the DOS
environment when the editor was invoked.  The ENV variable takes advantage of
AWK's ability to use strings as subscripts.  The variable name is used as a
subscript to access the value associated with that variable.  For example, if
the environment variable TMP has been set to the value C:\TEMP the value of
ENV["TMP"] will also be C:\TEMP.

Values in the ENV array may be changed or added in like manner through
assignment. For

Example:

  ENV["INCLUDE"] = "c:\include"

This new value for the environment variable is then in effect during the
remainder of the editing process, unless changed.


ΓòÉΓòÉΓòÉ 15.11.5. FS ΓòÉΓòÉΓòÉ

FS   Primitive

Purpose: Identifies the default AWK input field separator.

____________

Type: str FS

____________

Description:

The FS variable is used by the AWK split() function.  It defines what character
or characters the split() function uses as a default field separator.  The
initial value for this variable is " ", a single space.

____________

See also:  split()


ΓòÉΓòÉΓòÉ 15.11.6. language_template[] ΓòÉΓòÉΓòÉ

language_template   PEL

Purpose:  Store the curent template definition.

____________

Type:    str language_template[]

____________

Description: The language_template[] array holds the shortcut string and the
full template for the current template definition.

____________

See also:

o electric_mode
o expand_template()


ΓòÉΓòÉΓòÉ 15.11.7. OFS ΓòÉΓòÉΓòÉ

OFS   Primitive

Purpose: Identifies the AWK output field separator.

____________

Type: str OFS

____________

Description: The OFS variable is used by the AWK print() function.  It defines
what character or characters the print() function places between the
expressions it prints.  The initial value for this variable is " ", a single
space.


ΓòÉΓòÉΓòÉ 15.11.8. ORS ΓòÉΓòÉΓòÉ

ORS   Primitive

Purpose: Identifies the AWK output record separator.

____________

Type: str ORS

____________

Description: The ORS variable is used by the AWK print() function.  It defines
what character or characters print() outputs at the end of the expressions
printed.  The initial value of this variable is "\n", a new-line sequence.


ΓòÉΓòÉΓòÉ 15.11.9. SUBSEP ΓòÉΓòÉΓòÉ

SUBSEP   Primitive

Purpose: Sets string used to simulate multidimensional arrays.

____________

Type: str SUBSEP

____________

Description: Standard AWK does not support multidimensional arrays but allows
simulating them.  When you assign values to an array using multiple subscripts,
such as arr[i,j], AWK concatenates the j elements of i into a single string.
The elements are separated by the SUBSEP string.  The split() function may then
be used to access individual components.  The initial value for this variable
is "\x1C".


ΓòÉΓòÉΓòÉ 15.11.10. tags_path ΓòÉΓòÉΓòÉ

tags_path   PEL

Purpose:  Path the editor uses to find tags files

____________

Type:    str tags_path

____________

Description: The tags_path is the path the editor searches to find a tags file
when a tags() command is executed.  If the function being searched for does not
appear in a tags file, the next directory in the tags_path is searched.

____________


ΓòÉΓòÉΓòÉ 15.12. Resources ΓòÉΓòÉΓòÉ

resource_dll()
          Name of the resource file used by the editor.


ΓòÉΓòÉΓòÉ 15.12.1. resource_dll ΓòÉΓòÉΓòÉ

resource_dll  Read-Only   Primitive

Purpose: Name of the resource file used by the editor.

____________

Type:   str resource_dll

____________

Description:

The resource_dll variable contains the name of dll file that is used to load
resources by the editor.


ΓòÉΓòÉΓòÉ 15.13. Searching ΓòÉΓòÉΓòÉ

SEARCH_
          Constants used for search flags and masks.
replace_pattern
          Stores the replacement text used by replace operations.
replace_string_length
          Indicates the length of text replacing the search pattern.
search_count
          Defines how many repetitions of a search are desired.
search_cursor_offset
          Stores distance from cursor to beginning of match.
search_flags
          Dictates many of the standard searching parameters.
search_pattern
          Stores the matching pattern used during a search.
search_string_length
          Indicates the length of text matching the search pattern.
word_delimiter()
          Defines characters that delimit a word.


ΓòÉΓòÉΓòÉ 15.13.1. SEARCH_ ΓòÉΓòÉΓòÉ

SEARCH_   Primitive

Purpose:  Constants used for search flags and masks.

____________

Type:    const int SEARCH_

____________

Description: The constants defined in the _SEARCH section can be used as flags
to seach functions like search().  The constants may also be used as masks to
set and examine the search_flags variable.

o SEARCH_ADVANCE
o SEARCH_ALL_BUFFERS
o SEARCH_BACKWARD
o SEARCH_BKWD_REGEX
o SEARCH_BKWD_REGEX_ADV
o SEARCH_BKWD_REGEX_IG
o SEARCH_BKWD_REGEX_MAX
o SEARCH_BKWD_REGEX_MAX_IG
o SEARCH_BLOCK
o SEARCH_CASE
o SEARCH_CENTER_CURSOR
o SEARCH_DEFAULT
o SEARCH_FORWARD
o SEARCH_FWD_ADV
o SEARCH_FWD_IG
o SEARCH_FWD_REGEX
o SEARCH_FWD_REGEX_ADV
o SEARCH_FWD_REGEX_IG
o SEARCH_FWD_REGEX_MAX
o SEARCH_FWD_REGEX_MAX_IG
o SEARCH_GLOBAL
o SEARCH_HIGHLIGHT
o SEARCH_MARK_CHG
o SEARCH_MAXIMAL_MATCH
o SEARCH_ONCE_PER_LINE
o SEARCH_REGEX
o SEARCH_WHOLE_WORD
o SEARCH_WRAPS

____________

See also: search().


ΓòÉΓòÉΓòÉ 15.13.2. replace_pattern ΓòÉΓòÉΓòÉ

replace_pattern   PEL

Purpose: Stores the replacement text used by replace operations.

____________

Type: str replace_pattern

____________

Description: The replace_pattern variable contains the text which is intended
to replace the text matching the pattern of a directional replace functions for
matching.  The directional replace functions are as follows:

replace_forward()
replace_backward()

If there have been any previous replace operations using these functions, the
replace_pattern string will contain the pattern used in the last of these
operations.  This variable is not modified by the function replace().

The initial value for this variable is an empty string.


ΓòÉΓòÉΓòÉ 15.13.3. replace_string_length ΓòÉΓòÉΓòÉ

replace_string_length   Primitive

Purpose: Indicates the length of text replacing the search pattern.

____________

Type: int replace_string_length

____________

Description: The replace_string_length variable contains the length of the
replacement string resulting from the most recent replace operation.  This
value is primarily useful when Regular expressions searches result in strings
of uncertain length.  If you wish to manipulate the resulting text, the length
of the resulting string may be necessary.

This variable differs from the search_string_length variable in that
search_string_length is the length of the matching string before replacement.
The variable replace_string_length is the length after replacement.

____________

See also:   search_string_length


ΓòÉΓòÉΓòÉ 15.13.4. search_count ΓòÉΓòÉΓòÉ

search_count   Primitive

Purpose: Defines how many repetitions of a search are desired.

____________

Type: int search_count

____________

Description: The search_count variable sets the maximum number of search or
replace operations to be performed. The current search or replace operation is
repeated until the number of repetitions specified by search_count have been
performed or until no further matches are found.

The default value for this variable is zero.  When a search is executed with
search_count set to zero, the search will be executed for one repetition. Most
search and replace functions decrement this variable as search and replace
operations are performed.  This continues until search_count is zero or the
search/replace is completed.  The functions then reset this variable to zero.


ΓòÉΓòÉΓòÉ 15.13.5. search_cursor_offset ΓòÉΓòÉΓòÉ

search_cursor_offset   Primitive

Purpose: Stores distance from cursor to beginning of match.

____________

Type: int search_cursor_offset

____________

Description: The search_cursor_offset variable provides information about where
the cursor was positioned following Regular expressions searches.  This
variable contains the number of characters between the cursor position and the
beginning of matching text.  This variable will be set to zero unless the most
recent search or replace operation was a search using Regular expressions  In
addition, a cursor location must have been specified in the pattern.

This variable is most useful when you are building a function to automate some
editing operation.  It enables you to locate the beginning of matching text
even if you specified that the editor place the cursor after a matching group
of text.

____________

See also: Regular expressions


ΓòÉΓòÉΓòÉ 15.13.6. search_flags ΓòÉΓòÉΓòÉ

search_flags   PEL

Purpose: Dictates many of the standard searching parameters.

____________

Type: int search_flags

____________

Description: The first seven bits of the search_flags. variable are used by the
editor's standard search and replace function to determine various searching
parameters. A number of descriptive identifiers have been defined in the
standard function files.  These identifiers are listed in the SEARCH_ section.

When the bit corresponding to each of these parameters is set ( 1 ), that
parameter is turned on.  Otherwise, the parameter is turned off.

The default value for this variable is 23, which sets maximal match, search
block, search forward and use of regular expressions.  Keep in mind, however,
that various emulations may alter this setting.


ΓòÉΓòÉΓòÉ 15.13.6.1. SEARCH_MAXIMAL_MATCH ΓòÉΓòÉΓòÉ

SEARCH_MAXIMAL_MATCH(0x0001)

Determines whether the editor will attempt to match the smallest string
matching a given pattern or the largest.  This bit is only used if SEARCH_REGEX
has been enabled.  Under many conditions, it will not matter whether the
maximal or minimal match is used; in either case the same string will be
matched.  However, if part or all of the pattern may occur nested within or
contiguous to text which also matches the pattern, this parameter will effect
the outcome of the search.


ΓòÉΓòÉΓòÉ 15.13.6.2. SEARCH_BLOCK ΓòÉΓòÉΓòÉ

SEARCH_BLOCK (0x0002)

Determines whether searches are limited to the marked block or region, when one
is defined.


ΓòÉΓòÉΓòÉ 15.13.6.3. SEARCH_FORWARD ΓòÉΓòÉΓòÉ

SEARCH_FORWARD (0x0004)

Determines whether search or replace operations performed will search from the
current cursor position toward the end of the buffer.  Otherwise, the search
proceeds toward the beginning of the buffer.


ΓòÉΓòÉΓòÉ 15.13.6.4. SEARCH_WRAPS ΓòÉΓòÉΓòÉ

SEARCH_WRAPS (0x0008)

Determines whether search and replace operations are applied to the entire
buffer regardless of the location of the cursor.  This search is carried out by
first searching from the cursor position to the buffer extremity indicated by
the SEARCH_FORWARD bit.  The search then continues from the opposite buffer
extremity to the cursor position.  For example, a search from the cursor
position to the end of the buffer is continued from the beginning of the buffer
to the cursor position.

As with all searches, the search may be terminated earlier if the search is not
global and a match is found prior to searching the entire buffer.  When this
bit is zero the search continues only until the buffer extremity is reached.


ΓòÉΓòÉΓòÉ 15.13.6.5. SEARCH_REGEX ΓòÉΓòÉΓòÉ

SEARCH_REGEX (0x0010)

Determines whether the string supplied to a search or replace function is
considered a Regular expressions.  Regular expressions are described in detail
in the User's Manual, in the chapter "Regular Expressions".  When this variable
is set to zero, the search_pattern is treated as a simple string.


ΓòÉΓòÉΓòÉ 15.13.6.6. SEARCH_CASE ΓòÉΓòÉΓòÉ

SEARCH_CASE (0x0020)

Determines whether search and replace operation will make a distinction between
upper and lower case characters.  If the bit is zero, the characters of text
must have the same case as the supplied search pattern in order to be
considered a match. Otherwise, character case is not considered when
determining if matching text has been found.


ΓòÉΓòÉΓòÉ 15.13.6.7. SEARCH_ADVANCE ΓòÉΓòÉΓòÉ

SEARCH_ADVANCE (0x0040)

Determines whether whether or not a match was previously found.  This enables
the function to avoid matching the same text again. When this bit is set, the
search begins one character beyond the cursor in the direction of search.


ΓòÉΓòÉΓòÉ 15.13.6.8. SEARCH_ONCE_PER_LINE ΓòÉΓòÉΓòÉ

SEARCH_ONCE_PER_LINE (0x2000)

Determines whether the global replacement operations will be limited to one
replacement per line.


ΓòÉΓòÉΓòÉ 15.13.7. search_pattern ΓòÉΓòÉΓòÉ

search_pattern   PEL

Purpose: Stores the matching pattern used during a search.

____________

Type: str search_pattern

____________

Description: The search_pattern variable contains the pattern used during
directional search and replace functions for matching.  The directional search
and replace functions are as follows:

search_forward()
search_backward()
replace_forward()
replace_backward()

If there have been any previous search/replace operations using these
functions, the search_pattern string will contain the pattern used in the last
of these operations.  This variable is not modified by the functions search()
and replace().

This pattern may be either a regular expression or an ordinary string.  The
initial value for this variable is an empty string.


ΓòÉΓòÉΓòÉ 15.13.8. search_string_length ΓòÉΓòÉΓòÉ

search_string_length   Primitive

Purpose: Indicates the length of text matching the search pattern.

____________

Type: int search_string_length

____________

Description: The search_string_length variable contains the length of the
string matching the most recent search/replace operation.  This value is
primarily useful in writing functions that wish to manipulate the text matching
Regular expressions.

If the last search/replace operation was not successful, this variable will be
set to zero.

This variable differs from the replace_string_length variable in that
replace_string_length is the length of the string resulting from a replacement.
The variable search_string_length is the length before replacement.

____________

See also:   replace_string_length


ΓòÉΓòÉΓòÉ 15.13.9. word_delimiter ΓòÉΓòÉΓòÉ

word_delimiter   Primitive

Purpose: Defines characters that delimit a word.

____________

Type:   str word_delimiter

____________

Description:

The word_delimiter variable contains a list of characters that are not to be
considered part of a word.  This variable is used whenever functions on words
are performed.


ΓòÉΓòÉΓòÉ 15.14. String Manipulation ΓòÉΓòÉΓòÉ

RLENGTH
          Stores length of a string match resulting from match()
RSTART
          Stores the position of the match resulting from match()


ΓòÉΓòÉΓòÉ 15.14.1. RLENGTH ΓòÉΓòÉΓòÉ

RLENGTH   Primitive

Purpose: Stores length of a string match resulting from match()

____________

Type: int RLENGTH

____________

Description: After each use of the match() function the variable RLENGTH is set
to the length of the text matching the pattern specified in match().  If there
was no match found, the variable is set to zero.

____________

See also: RSTART


ΓòÉΓòÉΓòÉ 15.14.2. RSTART ΓòÉΓòÉΓòÉ

RSTART   Primitive

Purpose: Stores the position of the match resulting from match()

____________

Type: int RSTART

____________

Description: After each use of the match() function the variable RSTART is set
to the starting position of the text matching the pattern specified in match().
For example, if the match begins with the fifth character the value of RSTART
will be 5.  If there was no match found, the variable is set to zero.

____________

See also: RLENGTH


ΓòÉΓòÉΓòÉ 15.15. System Interface ΓòÉΓòÉΓòÉ

SYS_
          Constants used as flags for the system commands.
errno
          Stores error code from last DOS operation.
os_name
          Stores name of the operating system in use.
pipe_data
          Contains the last data read from the read_pipe when a PIPE_DATA_EVENT
          event occured.
stdaux
          Provides access to standard auxiliary device.
stderr
          Provides access to standard error device.
stdin
          Provides access to standard input device.
stdout
          Provides access to standard output device.
stdprn
          Provides access to standard line printer.


ΓòÉΓòÉΓòÉ 15.15.1. SYS_ ΓòÉΓòÉΓòÉ

SYS_   Primitive

Purpose:  Constants used as flags for the system commands.

____________

Type:    const int SYS_

____________

Description: The constants defined in the SYS_ section can be used as flags for
the system() command.  They define what kind of pipe is created.

o SYS_ASYNC
o SYS_CLOSE
o SYS_DETACHED
o SYS_MASK
o SYS_NOEXPOSE
o SYS_NONE
o SYS_NOSESSION
o SYS_PROMPT
o SYS_QUIET
o SYS_SESSION
o SYS_SHELL

____________


ΓòÉΓòÉΓòÉ 15.15.2. errno ΓòÉΓòÉΓòÉ

errno  read-only   Primitive

Purpose: Stores error code from last DOS operation.

____________

Type:   int errno

____________

Description:

The exit code returned by the last DOS command executed by the editor is stored
in the variable errno.  Consult this variable when a DOS or OS/2 operation
indicates an error has occurred.

This variable may not be modified by the user; only by the system.

____________

See also:  fread(), fwrite().


ΓòÉΓòÉΓòÉ 15.15.3. os_name ΓòÉΓòÉΓòÉ

os_name  read-only   Primitive

Purpose: Stores name of the operating system in use.

____________

Type: str os_name

____________

Description: The string variable os_name is set to either "Windows", "DOS", or
"OS/2" depending on the operating system you are using.  This enables
user-written programs to take actions that are conditional upon the operating
system present.  Note that the value will be "DOS" when run in OS/2's
DOS-compatibility box.

This variable is set by editor system and may not be modified by the user or
user-written macros.


ΓòÉΓòÉΓòÉ 15.15.4. pipe_data ΓòÉΓòÉΓòÉ

pipe_data   Primitive

Purpose:  Contains the last data read from the read_pipe when a PIPE_DATA_EVENT
event occured.

____________

Type:    Read-Only string pipe_data

____________

Description: When a PIPE_DATA_EVENT occurs, this holds the data read from the
pipe. It is undefined if accessed outside of a PIPE_DATA_EVENT handler.  This
variable may only be modified by the system.

____________

See also:  create_pipes(), close_pipes(), process_pipes(), system().


ΓòÉΓòÉΓòÉ 15.15.5. stdaux ΓòÉΓòÉΓòÉ

stdaux   Primitive

Purpose: Provides access to standard auxiliary device.

____________

Type: fileid stdaux

____________

Description: The file handle stdaux allows access to the DOS standard auxiliary
device.  Initially stdaux is COM1, however, it may be redirected.  Redirecting
or even closing stdaux will not effect the general operation of the editor.


ΓòÉΓòÉΓòÉ 15.15.6. stderr ΓòÉΓòÉΓòÉ

stderr   Primitive

Purpose: Provides access to standard error device.

____________

Type: fileid stderr

____________

Description: The file handle stderr allows access to the DOS standard error
device.  Initially stderr is the monitor, however, it may be redirected.
Redirecting or even closing stderr will not effect the general operation of the
editor.


ΓòÉΓòÉΓòÉ 15.15.7. stdin ΓòÉΓòÉΓòÉ

stdin   Primitive

Purpose: Provides access to standard input device.

____________

Type: fileid stdin

____________

Description: The file handle stdin allows access to the DOS standard input
device.  Initially stdin is the keyboard, however, it may be redirected.
Redirecting or even closing stdin will not effect the general operation of the
editor.


ΓòÉΓòÉΓòÉ 15.15.8. stdout ΓòÉΓòÉΓòÉ

stdout   Primitive

Purpose: Provides access to standard output device.

____________

Type: fileid stdout

____________

Description: The file handle stdout allows access to the DOS standard output
device.  Initially stdout is the monitor, however, it may be redirected.
Redirecting or even closing stdout will not effect the general operation of the
editor.


ΓòÉΓòÉΓòÉ 15.15.9. stdprn ΓòÉΓòÉΓòÉ

stdprn   Primitive

Purpose: Provides access to standard line printer.

____________

Type: fileid stdprn

____________

Description: The file handle stdprn allows access to the DOS standard printer
device.  Initially stdprn is LPT1, however, it may be redirected.  Redirecting
or even closing stdprn will not effect the general operation of the editor.


ΓòÉΓòÉΓòÉ 15.16. Toolbar ΓòÉΓòÉΓòÉ

TI_
          Constants used as flags to the toolbar functions.
toolbar_visible
          Indicates whether the toolbar is shown


ΓòÉΓòÉΓòÉ 15.16.1. TI_ ΓòÉΓòÉΓòÉ

TI_   Primitive

Purpose:  Constants used as flags to the toolbar functions.

____________

Type:    const int TI_

____________

Description: The constants defined in the TI_ section are used as flags to
calls of the functions that manipulate the toolbar.  The number ans type
parameters passed to the toolbar functions vary, depending on the flag.

o TI_DISABLED
o TI_DOWN
o TI_ENABLED
o TI_FUNCTIONID
o TI_ITEMBITMAP
o TI_UP

____________

See also: modify_toolbaritem(), toolbar_info().


ΓòÉΓòÉΓòÉ 15.16.2. toolbar_visible ΓòÉΓòÉΓòÉ

toolbar_visible   PEL

Purpose:  Indicates whether the toolbar is shown

____________

Type:    int toolbar_visible

____________

Description: The toolbar_visible variable stores a value (either TRUE or
FALSE), indicating whether the toolbar should be shown.  If it is TRUE, the
toolbar is displayed, otherwise the toolbar is not displayed.

____________


ΓòÉΓòÉΓòÉ 15.17. Types ΓòÉΓòÉΓòÉ

case_insensitive
          Indicate whether the current syntax highlighting type is case
          sensitive.
compilers[]
          Store the compiler information.
extensions[]
          Store the type to extension associations.
languages[]
          Store all the type information
languages_id
          Holds the current type name.
style_delimiter
          Holds the characters that are used as delimiters for syntax
          highlighting.
syntax_colors_bg
          Array of colors used for the syntax highlighting color palette.
syntax_colors_fg[]
          Array of colors used for the syntax highlighting color palette.
syntax_highlight
          Indicates whether syntax highlighting is turned on.
templates[]
          Store the type to template association.


ΓòÉΓòÉΓòÉ 15.17.1. case_insensitive ΓòÉΓòÉΓòÉ

case_insensitive   Primitive

Purpose:  Indicate whether the current syntax highlighting type is case
sensitive.

____________

Type:    int case_insensitive

____________

Description: The case_insensitive variable, if TRUE, indicates that the current
syntax highlighting type is not case sensitive in terms of identifying
keywords.

____________

See also:

o languages[]
o get_case_sensitive()


ΓòÉΓòÉΓòÉ 15.17.2. compilers[] ΓòÉΓòÉΓòÉ

compilers   PEL

Purpose:  Store the compiler information.

____________

Type:    str compilers[]

____________

Description: The compilers array is an array of compiler names.  The
information stored in the array is used when the compile_buffer() function is
called.  Each compiler can have the following information:

command_line
          The command line that is passed to the OS/2 command processor.  You
          can use a set of macros that are expanded before execution.
          (Compilers)
error_format
          String name of the predefined error format.
needs_input
          Flag indicating whether the compile will need input to complete.
input_file
          File containing input for compiles needing input.
list_all
          Lists all output from a compile, rather than just errors.
save_all
          Saves all modified buffers before starting the compile.
chdir
          Changes to the directory of the source file before doing the compile.
background
          Processes the compile in the background.
flags
          System command flags.
dos_settings
          DOS settings used to set up the DOS environment for DOS compiles.

____________

See also:

o languages[]


ΓòÉΓòÉΓòÉ 15.17.3. escape_character ΓòÉΓòÉΓòÉ

escape_character   Primitive

Purpose:  Store the character used to begin an escape sequence.

____________

Type:    str escape_character

____________

Description: The escape_character variable stores the character the editor uses
to identify escapable line styles.

____________

See also:

o languages[]
o EscapeCharacter()


ΓòÉΓòÉΓòÉ 15.17.4. extensions[] ΓòÉΓòÉΓòÉ

extensions   PEL

Purpose:  Store the type to extension associations.

____________

Type:    str extensions[]

____________

Description: The extensions array is an array indexed by file extension. The
elements of the array are the types mapped to the extensions.  For example:

extensions[".pel"] == "pel"
evaluates to TRUE.

____________

See also:

o languages[]


ΓòÉΓòÉΓòÉ 15.17.5. languages[] ΓòÉΓòÉΓòÉ

languages   Primitive

Purpose:  Store all the type information

____________

Type:    str languages[]

____________

Description:

The languages array holds all of the type specific information. This
information is applied to new buffers when the new_edit_file() function is
called.  The array is indexed by type and has the following members:


modified
          Flag that is turned on if the type has been modified in the settings
          notebook.
compiler_name
          Name of the compiler invoked when compile_buffer() is executed on a
          buffer of this type.
template
          Name of the template used for template expansion.
tab_stops
          String holding the tab stobs for the type.
margins
          String holding left and right margins.
matching_pairs
          String of matching pair constructs used by goto_matching().
esc_character
          Special character that can be used to prevent line styles from being
          highlighted.
buff_flags
          Set of buffer flags to be used for buffers of this type.
auto_indent
          Flag indicatiing whether auto indent is turned on.
syntax
          Flag indicating whether syntax highlihting is turned on.
stile_delimiters
          String of characters to be used as delimiters for syntax highlighting
          items.
sensitive
          Flag indicating whether the items defined for syntax highlighting are
          case sensitive.
expand
          Flag indicating whether template expansion is on.
category[]
          Array of syntax highlighting categories defined for the type.
keyword[]
          Array of items defined as keyword styles for syntax highlighting.
BufferFlags[]
          Array of items defined as BufferFlags styles for syntax highlighting.
line[]
          Array of items defined as line styles for syntax highlighting.

____________

See also:

o BufferFlags()


ΓòÉΓòÉΓòÉ 15.17.6. languages_id ΓòÉΓòÉΓòÉ

languages_id   Primitive

Purpose:  Holds the current type name.

____________

Type:    str languages_id

____________

Description: The languages_id stores the name of the current type.  It is used
as index into the languages[] array to find the items to highlight.

____________

See also:


ΓòÉΓòÉΓòÉ 15.17.7. style_delimiter ΓòÉΓòÉΓòÉ

style_delimiter   Primitive

Purpose:  Holds the characters that are used as delimiters for syntax
highlighting.

____________

Type:    str style_delimiter

____________

Description: The style_delimiter variable holds the string of characters that
the editor used to delimit keywords for syntax highlighting.  A keyword will
not be highlighted unless it is surrounded by delimiters.  Whitespace is
automatically included in this string so do not have to be included by the
user.

____________

See also:

o languages[]
o StyleDelimiters()


ΓòÉΓòÉΓòÉ 15.17.8. syntax_colors_bg[] ΓòÉΓòÉΓòÉ

syntax_colors_bg   PEL

Purpose:  Array of colors used for the syntax highlighting color palette.

____________

Type:    long syntax_colors_bg[]

____________

Description: The syntax_colors_bg[] array hold the colors that fill the
background color palette for syntax highlighting dialogs.  The colors in this
array may be changed manually in language.pel or through the Configure Color
dialog in the settings_notebook().

____________

See also:

o syntax_colors_fg[]


ΓòÉΓòÉΓòÉ 15.17.9. syntax_colors_fg ΓòÉΓòÉΓòÉ

syntax_colors_fg   PEL

Purpose:  Array of colors used for the syntax highlighting color palette.

____________

Type:    long syntax_colors_fg[]

____________

Description: The syntax_colors_fg[] array hold the colors that fill the
foreground color palette for syntax highlighting dialogs.  The colors in this
array may be changed manually in language.pel or through the Configure Color
dialog in the settings_notebook().

____________

See also:

o syntax_colors_bg


ΓòÉΓòÉΓòÉ 15.17.10. syntax_highlight ΓòÉΓòÉΓòÉ

syntax_highlight   Primitive

Purpose:  Indicates whether syntax highlighting is turned on.

____________

Type:    int syntax_highlight

____________

Description: The syntax_highlight variable is a buffer specific variable that
tells whether the current buffer has syntax highlighting turned on. This
variable is set by syntax highlighting field of the type structure.

____________

See also:

o languages[]
o Syntax()


ΓòÉΓòÉΓòÉ 15.17.11. templates[] ΓòÉΓòÉΓòÉ

templates   PEL

Purpose:  Store the type to template association.

____________

Type:    str templates[]

____________

Description: The templates array is an array indexed by type. The elements of
the array are the templates mapped to the types.  For example:

templates["pel"] == "awk"
evaluates to TRUE.

____________

See also:

o languages[]


ΓòÉΓòÉΓòÉ 15.18. User Interface ΓòÉΓòÉΓòÉ

keyboard_flags()
          Stores the keyboard status byte.
keyboard_input_pending
          Indicates that a keystroke is waiting to be read.
last_message
          Contains the last displayed warning or error message.
mouse_display_x
          Tells which text column the mouse cursor occupies.
mouse_display_y
          Tells which text line the mouse cursor occupies.
mouse_event_column
          Contains the column in the buffer at which the mouse was last
          clicked.
mouse_event_digit
          Contains the digit of the hex humber that the mouse was clicked, for
          hex-dump mode.
mouse_event_line
          Contains the column in the buffer where the mouse was last
          positioned.
mouse_event_offset
          Contains the buffer offset at which the mouse was last clicked.
mouse_event_side
          Contains the side (number or ASCII) of the dump in which the mouse
          was clicked, for hex-dump mode.
mouse_event_x
          Stores column offset of mouse when last clicked.
mouse_event_y
          Stores line offset of mouse when last clicked.
mouse_pixel_x()
          Mouse X position in pixels.
mouse_pixel_y()
          Mouse Y position in pixels.
prompt_response
          Stores input from user.


ΓòÉΓòÉΓòÉ 15.18.1. keyboard_flags ΓòÉΓòÉΓòÉ

keyboard_flags  read-only   Primitive

Purpose: Stores the keyboard status byte.

____________

Type: int keyboard_flags

____________

Description:

The keyboard_flags variable is a copy of the current DOS "keyboard status
byte." The first eight bits of this variable (numbered from 0 to 7) are used as
flags to indicate the status of various shift and toggle keys.  When the bit is
set (when it has a 1 value), the key is pressed or the toggle is on.  When the
bit is zero, the key has not been pressed, or the toggle is off.

The table below shows which key or toggle is associated with each of these
bits:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéBit #  ΓöéKey or Toggle       ΓöéHex mask  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé0      ΓöéRight shift key     Γöé01H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé1      ΓöéLeft shift key      Γöé02H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé2      ΓöéControl key         Γöé04H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé3      ΓöéAlt key             Γöé08H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé4      ΓöéScroll lock toggle  Γöé10H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé5      ΓöéNum lock toggle     Γöé20H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé6      ΓöéCaps lock toggle    Γöé40H       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé7      ΓöéInsert toggle       Γöé80H       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ

Bits 0 through 3 of this variable are set by the system and may not be modified
by the user or user programs.  Bits 4 through 7 may be interrogated or changed
by the user.  This allows the user to change the setting of these toggle keys.


ΓòÉΓòÉΓòÉ 15.18.2. keyboard_input_pending ΓòÉΓòÉΓòÉ

keyboard_input_pending   Primitive

Purpose: Indicates that a keystroke is waiting to be read.

____________

Type: int keyboard_input_pending

____________

Description:

This variable is set to a non-zero (TRUE) value when one or more characters of
keyboard input are waiting to be processed. When the keyboard buffer is empty,
the keyboard_input_pending variable is set to zero (FALSE).  Pending characters
may be read with either the getchar() or getkey() functions.

This variable is set by the system and may not be modified by the user.

____________

See also:  getchar(), getkey()


ΓòÉΓòÉΓòÉ 15.18.3. last_message ΓòÉΓòÉΓòÉ

last_message  read-only   Primitive

Purpose: Contains the last displayed warning or error message.

____________

Type: str last_message

____________

Description: The last_message variable contains the text of the last message
printed to the screen with the error(), warning(), or message() function.  This
allows the user to re-display the message or write a function that examines its
contents. This variable is set by the system and may not be modified by the
user.

____________

See also:   message(), notify(), warning(), error()


ΓòÉΓòÉΓòÉ 15.18.4. mouse_display_x ΓòÉΓòÉΓòÉ

mouse_display_x   Primitive

Purpose: Tells which text column the mouse cursor occupies.

____________

Type: int mouse_display_x

____________

Description: The mouse_display_x variable stores the current screen column
occupied by the mouse.  This count begins with column 0 at the left edge of the
display.  together with mouse_display_y, this variable defines the current
mouse position.

Assigning a value to this variable changes the horizontal position of the mouse
cursor.


ΓòÉΓòÉΓòÉ 15.18.5. mouse_display_y ΓòÉΓòÉΓòÉ

mouse_display_y   Primitive

Purpose: Tells which text line the mouse cursor occupies.

____________

Type: int mouse_display_y

____________

Description: The mouse_display_y variable stores the current screen line
occupied by the mouse.  This count begins with line 0 at the top of the
display. Together with mouse_display_x, this variable defines the current mouse
position.

Assigning a value to this variable changes the vertical position of the mouse
cursor.


ΓòÉΓòÉΓòÉ 15.18.6. mouse_event_column ΓòÉΓòÉΓòÉ

mouse_event_column.   read only,   Primitive

Purpose: Contains the column in the buffer at which the mouse was last clicked.

____________

Type: short mouse_event_column

____________

Description: The mouse_event_column variable contains the column in the buffer
that corresponds to the position on the window that was last clicked on.  It is
used to determine where to position the cursor when the mouse is clicked.  If
the goto_pos() function is called with mouse_event_line and mouse_event_column
passed to it, the mouse will be positioned where the mouse was clicked.
However, if hex-dump mode is on, the mouse may not be positioned correctly.
Use goto_buffer_offset()(mouse_event_offset) for hex-dump mode.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 15.18.7. mouse_event_digit ΓòÉΓòÉΓòÉ

mouse_event_digit.   read only,   Primitive

Purpose: Contains the digit of the hex humber that the mouse was clicked, for
hex-dump mode.

____________

Type: short mouse_event_digit

____________

Description:  In hex-dump mode, when the mouse is clicked on the number side
(mouse_event_side=1), the mouse_event_digit variable contains the digit of the
number on which the mouse was clicked.  If you are not in hex-dump mode or the
mouse was clicked on the aSCII side (mouse_event_side=0), it contains 0.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 15.18.8. mouse_event_line ΓòÉΓòÉΓòÉ

mouse_event_line   read only,   Primitive

Purpose: Contains the column in the buffer where the mouse was last positioned.

____________

Type: short mouse_event_line

____________

Description: The mouse_event_line variable contains the column in the buffer
that corresponds to the position on the window that was last clicked on.  It is
used to determine where to position the cursor when the mouse is clicked.  If
goto_pos() is called with mouse_event_line and mouse_event_column passed to it,
the mouse will be positioned where the mouse was last clicked.  However, if
hex-dump mode is on, the mouse may not be positioned quite correctly.  Use
goto_buffer_offset() (mouse_event_offset) for hex-dump mode.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 15.18.9. mouse_event_offset ΓòÉΓòÉΓòÉ

mouse_event_offset.

Purpose: Contains the buffer offset at which the mouse was last clicked.

____________

Type: short mouse_event_offset

____________

Description: The mouse_event_offset variable contains the buffer offset that
corresponds to the position on the window that was last active, or clicked on.
It is used in hex-dump mode to determine where to position the cursor when the
mouse is clicked.

If the goto_buffer_offset() function is called with mouse_event_offset passed
to it, the mouse will be positioned where the mouse was last clicked. In
hex-dump mode, if hex-dump mode is not on, the mouse will be positioned as
close to the mouse click as possible while staying in "real space."


ΓòÉΓòÉΓòÉ 15.18.10. mouse_event_side ΓòÉΓòÉΓòÉ

mouse_event_side   read only,   Primitive

Purpose:  Contains the side (number or ASCII) of the dump in which the mouse
was clicked, for hex-dump mode.

____________

Type:  short mouse_event_side

____________

Description:  In hex-dump mode, the mouse_event_side variable contains the side
ofthe cump screen that the mouse was clicked on. (Number side=1, ASCII side=0.)
If hex-dump mode is not on, this variable contains 0.

____________

Value returned: None.


ΓòÉΓòÉΓòÉ 15.18.11. mouse_event_x ΓòÉΓòÉΓòÉ

mouse_event_x   Primitive

Purpose: Stores column offset of mouse when last clicked.

____________

Type: int mouse_event_x

____________

Description: The mouse_event_x variable contains the column offset of the mouse
cursor at the time the last "mouse event" occurred.  A mouse event is a mouse
button press or release.  Together with mouse_event_y, this variable allows you
to determine at what the mouse was pointing when one or more of the mouse keys
were used.

Keep in mind that screen positions differ from buffer positions in that the
former are offset, and therefore zero origin, while the latter count begins
with one.  This variable represents a screen position.

The value of this variable is updated whenever a mouse event occurs.  The
various the editor mouse events are described in the "User Interface" chapter
in Part One of this manual.


ΓòÉΓòÉΓòÉ 15.18.12. mouse_event_y ΓòÉΓòÉΓòÉ

mouse_event_y   Primitive

Purpose: Stores line offset of mouse when last clicked.

____________

Type: int mouse_event_y

____________

Description: The mouse_event_y variable contains the line offset of the mouse
cursor at the time the last mouse event occurred.  Together with mouse_event_x,
this variable allows you to determine at what the mouse was pointing when one
or more of the mouse keys were used.

Keep in mind that screen positions differ from buffer positions in that the
former are offset, and therefore zero origin, while the latter count begins
with one.  This variable represents a screen position.

The value of this variable is updated whenever a mouse event occurs.  The
various mouse events are described in the "User Interface" chapter in Part One
of this manual.


ΓòÉΓòÉΓòÉ 15.18.13. mouse_pixel_x ΓòÉΓòÉΓòÉ

mouse_pixel_x   Primitive

Purpose: Mouse X position in pixels.

____________

Type:   str mouse_pixel_x

____________

Description:

The mouse_pixel_x variable contains the x position of the mouse cursor.


ΓòÉΓòÉΓòÉ 15.18.14. mouse_pixel_y ΓòÉΓòÉΓòÉ

mouse_pixel_y   Primitive

Purpose: Mouse Y position in pixels.

____________

Type:   str mouse_pixel_y

____________

Description:

The mouse_pixel_y variable contains the y position of the mouse cursor.


ΓòÉΓòÉΓòÉ 15.18.15. prompt_response ΓòÉΓòÉΓòÉ

prompt_response   Primitive

Purpose: Stores input from user.

____________

Type: str prompt_response

____________

Description: The prompt_response variable is used by library functions that
prompt the user for input.  These functions treat the contents of
prompt_response as user input.

Through the use of an Event, the contents of this variable may be modified as
the user is being prompted.  For example, pressing the up arrow when prompted
could be made to cause the result of a previous prompt to be assigned to
prompt_response. The prompting function could then receive this as input from
the user.

See the "Event Handling" chapter in Part One of this manual for details of
event handling.


ΓòÉΓòÉΓòÉ 15.19. Version Control System ΓòÉΓòÉΓòÉ

PVCS_
          Constants used to turn on different features of your VCS.
default_get_command
          Stores default get command for your version control system.
default_put_command
          Stores default put command for your version control system.
default_vdiff_command
          Stores default vdiff command for PVCS.
get_command
          Specify get command for your version control system.
put_command
          Specify put command for your version control system.
vdiff_command
          PVCS Vdiff command (compare files)


ΓòÉΓòÉΓòÉ 15.19.1. PVCS_ ΓòÉΓòÉΓòÉ

PVCS_   Primitive

Purpose:  Constants used to turn on different features of your VCS.

____________

Type:    const int PVCS_

____________

Description: The constants defined in the PVCS_ section are used as flags to
calls of the functions that toggle the state of the version control system.

o PVCS_DISABLED
o PVCS_ENABLE_EMPTY_GETS
o PVCS_ENABLE_GETS

____________

See also: pvcs().


ΓòÉΓòÉΓòÉ 15.19.2. default_get_command ΓòÉΓòÉΓòÉ

default_get_command   PEL

Purpose:  Stores default get command for your version control system.

____________

Type:    str default_get_command

____________

Description: The default_get_command is the default command used when the
editor performs a vcs get.  If the get_command is not specified, the
default_get_command is used instead.  It can be specified on the VCS page of
the settings notebook.

____________


ΓòÉΓòÉΓòÉ 15.19.3. default_put_command ΓòÉΓòÉΓòÉ

default_put_command   PEL

Purpose:  Stores default put command for your version control system.

____________

Type:    str default_put_command

____________

Description: The default_put_command is the default command used when the
editor performs a vcs put.  If the put_command is not specified, the
default_put_command is used instead.  It can be specified on the VCS page of
the settings notebook.

____________


ΓòÉΓòÉΓòÉ 15.19.4. default_vdiff_command ΓòÉΓòÉΓòÉ

default_vdiff_command   PEL

Purpose:  Stores default vdiff command for PVCS.

____________

Type:    str default_vdiff_command

____________

Description: The default_vdiff_command is the default command used when the
editor performs a PVCS vdiff.  If the vdiff_command is not specified, the
default_vdiff_command is used instead.  The editor currently only supports PVCS
vdiff commands.

____________


ΓòÉΓòÉΓòÉ 15.19.5. get_command ΓòÉΓòÉΓòÉ

get_command   PEL

Purpose:  Specify get command for your version control system.

____________

Type:    str get_command

____________

Description: The get_command is the command used when the editor performs a vcs
get.  It can be specified on the VCS page of the settings notebook.

____________


ΓòÉΓòÉΓòÉ 15.19.6. put_command ΓòÉΓòÉΓòÉ

put_command   PEL

Purpose:  Specify put command for your version control system.

____________

Type:    str put_command

____________

Description: The put_command is the command used when the editor performs a vcs
put.  It can be specified on the VCS page of the settings notebook.

____________


ΓòÉΓòÉΓòÉ 15.19.7. vdiff_command ΓòÉΓòÉΓòÉ

vdiff_command   PEL

Purpose:  PVCS Vdiff command (compare files)

____________

Type:    str vdiff_command

____________

Description: The vdiff_command is the command the editor issues when asked to
perform a PVCS Vdiff.  Two windows are displayed side by side with the current
buffer on the right.  Differences between the current buffer and the last
version are highlighted.

____________


ΓòÉΓòÉΓòÉ 15.20. Windowing ΓòÉΓòÉΓòÉ

WINDOW_
          Constants used as masks and to set window flags.
auto_indent_mode
          Indicates if new lines are automatically indented.
current_window
          Stores the id number of the current window.
default_dump_bytes_per_line
          Contains the default number of bytes to be displayed per line in
          hex-dump mode.
default_linenumber_format
          Determines if and how line numbers are displayed when a new window is
          created.
default_scroll_context_bottom
          Scrolling margin honored by cursor at screen bottom.
default_scroll_context_left
          Scrolling margin honored by cursor at screen left.
default_scroll_context_right
          Scrolling margin honored by cursor at screen right.
default_scroll_context_top
          Scrolling margin honored by cursor at screen top.
default_scroll_means_pan
          Indicates whether movements apply to cursor or text.
default_scroll_unit_horizontal
          Stores number of columns in horizontal scrolling unit.
default_scroll_unit_vertical
          Stores the number of lines in vertical scrolling unit.
default_visible_newlines
          Defines string displayed to indicate end of line.
default_visible_spaces
          Defines appearance of a space on-screen.
default_visible_tabs
          Defines appearance of a tab on-screen.
default_visible_virtual_lines
          Defines appearance of lines beyond end of buffer
default_visible_virtual_spaces
          Defines appearance of virtual spaces on-screen.
default_window_flags
          Stores a number of window attributes as flags.
default_window_page_offset
          Cursor line position used when window is re-drawn.
default_window_page_overlap
          Defines how many lines are retained after paging.
dump_bytes_per_line
          Contains the number of bytes to be displayed per line in hex mode.
dump_digit
          Contains the current digit that the cursor is on in hex-dump mode.
mdi_mode
          Determines the document interface mode.
visible_newlines
          Defines string displayed to indicate end of line.
visible_spaces
          Defines appearance of a space on-screen.
visible_tabs
          Defines appearance of a tab on-screen.
visible_virtual_lines
          Defines appearance of lines beyond end of buffer
visible_virtual_spaces
          Defines appearance of virtual spaces on-screen.
window_first
          Stores line number of the first line of text in a window.
window_flags
          Stores a number of window attributes as flags.
window_height
          Tells over-all height of the current window in lines.
window_margin
          Tells the number of columns off-screen to the left.
window_name
          Stores a name for display in a window's title bar.
window_page_offset
          Cursor line position used when window is re-drawn.
window_page_overlap
          Defines how many lines are retained after paging.
window_text_height
          Tells how many lines of text a window may contain.
window_text_width()
          Tells how many columns of text a window contains.
window_text_x0
          Tells the column offset of text in the window.
window_text_y0
          Tells the line offset of text in the window.
window_width
          Tells how many columns the current window contains.
window_x0
          Tells the column offset of the window.
window_y0
          Tells the line offset of the window.


ΓòÉΓòÉΓòÉ 15.20.1. WINDOW_ ΓòÉΓòÉΓòÉ

WINDOW_   PEL

Purpose:  Constants used as masks and to set window flags.

____________

Type:    const int WINDOW_

____________

Description: The constants defined in the WINDOW_ section are used to set the
window_flags variable.  They can also be used as masks to examine the bits of
the window_flags variable.

o WINDOW_BORDERS
o WINDOW_CARAT
o WINDOW_CHARS
o WINDOW_COLLAPSED
o WINDOW_DISPLAY_FULL_FILENAME
o WINDOW_EXPANDED
o WINDOW_HEX
o WINDOW_HIDDEN
o WINDOW_HORIZ_SB
o WINDOW_IBM
o WINDOW_MAX_BOX
o WINDOW_MIN_BOX
o WINDOW_MIN_HEIGHT
o WINDOW_MIN_WIDTH
o WINDOW_NOBORDER
o WINDOW_NORMAL
o WINDOW_NORM_BORDER
o WINDOW_NO_TITLE
o WINDOW_OCTAL
o WINDOW_PLAIN
o WINDOW_SCROLLBARS
o WINDOW_SIZE_BORDER
o WINDOW_STANDARD
o WINDOW_STANDARD_MDI
o WINDOW_STANDARD_SDI
o WINDOW_SYSTEM
o WINDOW_SYS_MENU
o WINDOW_TITLE
o WINDOW_TITLEBAR
o WINDOW_VERT_SB
o WINDOW_ZOOM

____________

See also: create_window(), window_flags.


ΓòÉΓòÉΓòÉ 15.20.2. auto_indent_mode ΓòÉΓòÉΓòÉ

auto_indent_mode   Primitive

Purpose: Indicates if new lines are automatically indented.

____________

Type:   int auto_indent_mode

____________

Description:

If the auto_indent_mode variable is set then new lines are indented to the same
indention level as the previous line.  The indention level of a line is
determined by the amount of whitespace (spaces or tabs) preceding the first
character on the line.


ΓòÉΓòÉΓòÉ 15.20.3. current_window ΓòÉΓòÉΓòÉ

current_window   Primitive

Purpose: Stores the id number of the current window.

____________

Type: winid current_window

____________

Description:

The current_window variable contains the id number of the currently active
window.  The window id is the number assigned to the window by the system at
the time of its creation with the create_window function.

This variable may be read, used in comparisons and may be assigned any valid
window id.  Keep in mind that in making assignments to current_window that
buffer associated with the window you make current will become current.  For
this reason changing the value of current_window usually results in a new value
for current_buffer as well.


ΓòÉΓòÉΓòÉ 15.20.4. default_dump_bytes_per_line ΓòÉΓòÉΓòÉ

default_dump_bytes_per_line   read only   Primitive

Purpose: Contains the default number of bytes to be displayed per line in
hex-dump mode.

____________

Type: short default_dump_bytes_per_line

____________

Description: The default_dump_bytes_per_line variable is used in hex-dump mode
to determine the number of bytes to display on a line in hex-dump mode. The
system default value for this variable is 16, but it may be changed.

____________

See also: dump_bytes_per_line


ΓòÉΓòÉΓòÉ 15.20.5. dump_bytes_per_line() ΓòÉΓòÉΓòÉ

dump_bytes_per_line.   Primitive

Purpose: Contains the number of bytes to be displayed per line in hex mode.

____________

Type: short dump_bytes_per_line

____________

Description: The dump_bytes_per_line variable is used in hex-dump mode to
determine the number of bytes to display on a line.

____________

See also:  default_dump_bytes_per_line, window_flags


ΓòÉΓòÉΓòÉ 15.20.6. dump_digit ΓòÉΓòÉΓòÉ

dump_digit.   read only,   Primitive

Purpose: Contains the current digit that the cursor is on in hex-dump mode.

____________

Type: short dump_digit

____________

Description: The dump_digit window variable is used in hex-dump mode, when the
WINDOW_NUM_SIDE window flag is on, to determine what digit of the number to
place the cursor on.

____________

See also: window_flags


ΓòÉΓòÉΓòÉ 15.20.7. default_linenumber_format ΓòÉΓòÉΓòÉ

default_linenumber_format   Primitive

Purpose: Determines if and how line numbers are displayed when a new window is
created.

____________

Type:   str default_linenumber_format

____________

Description:

The default_linenumber_format variable contains the initial value of the
linenumber_format variable when a new buffer is created.

____________

See also:  linenumber_format


ΓòÉΓòÉΓòÉ 15.20.8. default_scroll_context_bottom ΓòÉΓòÉΓòÉ

default_scroll_context_bottom   Primitive

Purpose: Scrolling margin honored by cursor at screen bottom.

____________

Type:   int default_scroll_context_bottom

____________

Description:

The default_scroll_context_bottom variable contains the initial value of the
scroll_context_bottom variable when a new buffer is created.

____________

See also:  scroll_context_bottom


ΓòÉΓòÉΓòÉ 15.20.9. default_scroll_context_left ΓòÉΓòÉΓòÉ

default_scroll_context_left   Primitive

Purpose: Scrolling margin honored by cursor at screen left.

____________

Type:   int default_scroll_context_left

____________

Description:

The default_scroll_context_left variable contains the initial value of the
scroll_context_left variable when a new buffer is created.

____________

See also:  scroll_context_left


ΓòÉΓòÉΓòÉ 15.20.10. default_scroll_context_right ΓòÉΓòÉΓòÉ

default_scroll_context_right   Primitive

Purpose: Scrolling margin honored by cursor at screen right.

____________

Type:   int default_scroll_context_right

____________

Description:

The default_scroll_context_right variable contains the initial value of the
scroll_context_right variable when a new buffer is created.

____________

See also:  scroll_context_right


ΓòÉΓòÉΓòÉ 15.20.11. default_scroll_context_top ΓòÉΓòÉΓòÉ

default_scroll_context_top   Primitive

Purpose: Scrolling margin honored by cursor at screen top.

____________

Type:   int default_scroll_context_top

____________

Description:

The default_scroll_context_top variable contains the initial value of the
scroll_context_top variable when a new buffer is created.

____________

See also:  scroll_context_top


ΓòÉΓòÉΓòÉ 15.20.12. default_scroll_means_pan ΓòÉΓòÉΓòÉ

default_scroll_means_pan   Primitive

Purpose: Indicates whether movements apply to cursor or text.

____________

Type:   int default_scroll_means_pan

____________

Description:

The default_scroll_means_pan variable contains the initial value of the
scroll_means_pan variable when a new buffer is created.

____________

See also:  scroll_means_pan


ΓòÉΓòÉΓòÉ 15.20.13. default_scroll_unit_horizontal ΓòÉΓòÉΓòÉ

default_scroll_unit_horizontal   Primitive

Purpose: Stores number of columns in horizontal scrolling unit.

____________

Type:   int default_scroll_unit_horizontal

____________

Description:

The default_scroll_unit_horizontal variable contains the initial value of the
scroll_unit_horizontal variable when a new buffer is created.

____________

See also:  scroll_unit_horizontal


ΓòÉΓòÉΓòÉ 15.20.14. default_scroll_unit_vertical ΓòÉΓòÉΓòÉ

default_scroll_unit_vertical   Primitive

Purpose: Stores the number of lines in vertical scrolling unit.

____________

Type:   int default_scroll_unit_vertical

____________

Description:

The default_scroll_unit_vertical variable contains the initial value of the
scroll_unit_vertical variable when a new buffer is created.

____________

See also:  scroll_unit_vertical


ΓòÉΓòÉΓòÉ 15.20.15. default_visible_newlines ΓòÉΓòÉΓòÉ

default_visible_newlines   Primitive

Purpose: Defines string displayed to indicate end of line.

____________

Type:   str default_visible_newlines

____________

Description:

The default_visible_newlines variable contains the initial value of the
visible_newlines variable when a new buffer is created.

____________

See also:  visible_newlines


ΓòÉΓòÉΓòÉ 15.20.16. default_visible_spaces ΓòÉΓòÉΓòÉ

default_visible_spaces   Primitive

Purpose: Defines appearance of a space on-screen.

____________

Type:   str default_visible_spaces

____________

Description:

The default_visible_spaces variable contains the initial value of the
visible_spaces variable when a new buffer is created.

____________

See also:  visible_spaces


ΓòÉΓòÉΓòÉ 15.20.17. default_visible_tabs ΓòÉΓòÉΓòÉ

default_visible_tabs   Primitive

Purpose: Defines appearance of a tab on-screen.

____________

Type:   str default_visible_tabs

____________

Description:

The default_visible_tabs variable contains the initial value of the
visible_tabs variable when a new buffer is created.

____________

See also:  visible_tabs


ΓòÉΓòÉΓòÉ 15.20.18. default_visible_virtual_lines ΓòÉΓòÉΓòÉ

default_visible_virtual_lines   Primitive

Purpose: Defines appearance of lines beyond end of buffer

____________

Type:   str default_visible_virtual_lines

____________

Description:

The default_visible_virtual_lines variable contains the initial value of the
visible_virtual_lines variable when a new buffer is created.

____________

See also:  visible_virtual_lines


ΓòÉΓòÉΓòÉ 15.20.19. default_visible_virtual_spaces ΓòÉΓòÉΓòÉ

default_visible_virtual_spaces   Primitive

Purpose: Defines appearance of virtual spaces on-screen.

____________

Type:   str default_visible_virtual_spaces

____________

Description:

The default_visible_virtual_spaces variable contains the initial value of the
visible_virtual_spaces variable when a new buffer is created.

____________

See also:  visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.20.20. default_window_flags ΓòÉΓòÉΓòÉ

default_window_flags   Primitive

Purpose: Stores a number of window attributes as flags.

____________

Type:   int default_window_flags

____________

Description:

The default_window_flags variable contains the initial value of the
window_flags variable when a new window is created.

____________

See also:  window_flags


ΓòÉΓòÉΓòÉ 15.20.21. default_window_page_offset ΓòÉΓòÉΓòÉ

default_window_page_offset   Primitive

Purpose: Cursor line position used when window is re-drawn.

____________

Type:   int default_window_page_offset

____________

Description:

The default_window_page_offset variable contains the initial value of the
window_page_offset variable when a new buffer is created.

____________

See also:  window_page_offset


ΓòÉΓòÉΓòÉ 15.20.22. default_window_page_overlap ΓòÉΓòÉΓòÉ

default_window_page_overlap   Primitive

Purpose: Defines how many lines are retained after paging.

____________

Type:   int default_window_page_overlap

____________

Description:

The default_window_page_overlap variable contains the initial value of the
window_page_overlap variable when a new buffer is created.

____________

See also:  window_page_overlap


ΓòÉΓòÉΓòÉ 15.20.23. mdi_mode ΓòÉΓòÉΓòÉ

mdi_mode   Primitive

Purpose:  Determines the document interface mode.

____________

Type:    int mdi_mode

____________

Description: The mdi_mode variable tells whether the editor is in single or
multiple document interface mode.  If mdi_mode is FALSE, the editor is in SDI,
if TRUE, the editor is in MDI.

____________


ΓòÉΓòÉΓòÉ 15.20.24. visible_newlines ΓòÉΓòÉΓòÉ

visible_newlines   Primitive

Purpose: Defines string displayed to indicate end of line.

____________

Type: str visible_newlines

____________

Description: Each window has a visible_newlines variable associated with it.
The visible_newlines variable is a string displayed at the end of each line.
By default, this string is empty, which means that the end of the line is not
visibly marked.  In any case, this string is not stored in the file, but only
appears on the screen.

If it is desirable to see where each line ends, a single character or string of
characters may be assigned to this variable.  These characters then appear
immediately to the left of the last character on the line.

Typical values for this variable include the following:  "\x11" ( a triangle
pointing left ), "\x11\xd9", ( a triangle followed by a corner ), "\x14" ( a
paragraph symbol ).

This variable takes its initial value from the global variable
default_visible_newlines at the time the buffer is created.

____________

See also:   visible_end_buffer,visible_spaces, visible_tabs,
visible_virtual_lines, visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.20.25. visible_spaces ΓòÉΓòÉΓòÉ

visible_spaces window   Primitive

Purpose: Defines appearance of a space on-screen.

____________

Type: str visible_spaces

____________

Description: Each window has a visible_spaces variable associated with it.  The
visible_spaces variable is a one character string that is displayed wherever a
space character occurs in the buffer.  The string may contain more than one
character but only the first character is used.  By default, this string
contains a space, which means that spaces represent themselves.  Changing this
string, however, does not change the text stored in the file or the contents of
the buffer.  Only the appearance on the screen is affected.

If it is desirable for spaces to have a graphical representation, a single
character or string of characters may be assigned to this variable. Normally,
only one character is assigned to this string.  A typical value for this
string, other than its default value, is "\xfa", which appears as a small dot.

This variable takes its initial value from the global variable
default_visible_spaces at the time the buffer is created.

____________

See also:   visible_end_buffer, visible_newlines, visible_tabs,
visible_virtual_lines, visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.20.26. visible_tabs ΓòÉΓòÉΓòÉ

visible_tabs   Primitive

Purpose: Defines appearance of a tab on-screen.

____________

Type: str visible_tabs

____________

Description: Each window has a visible_tabs variable associated with it.  The
visible_tabs variable is a string displayed wherever a tab character occurs in
the buffer.  By default, this string contains a tab, which means that tabs
represent themselves. Changing this string, however, does not change the text
stored in the file or the contents of the buffer.  Only the appearance on the
screen is affected.

If it is desirable for tabs to have a graphical representation, a single
character or string of characters may be assigned to this variable. Normally,
only one character is assigned to this string.  A typical value for this
string, other than its default value, is "\x1a", which appears an arrow
pointing to the right.

This variable takes its initial value from the global variable
default_visible_tabs at the time the buffer is created.

____________

See also:   visible_end_buffer, visible_newlines, visible_spaces,
visible_virtual_lines, visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.20.27. visible_virtual_lines ΓòÉΓòÉΓòÉ

visible_virtual_lines   Primitive

Purpose: Defines appearance of lines beyond end of buffer

____________

Type: str visible_virtual_lines

____________

Description: Each window has a visible_virtual_lines variable associated with
it.  The visible_virtual_lines variable is a string displayed on screen lines
that are beyond the end of the buffer.  By default, this string is empty, which
means that these lines are not visibly marked.  In any case, this string is not
stored in the file, but only appears on the screen.

If it is desirable a visual cue to indicate lines not contained in the buffer,
a single character or string of characters may be assigned to this variable.  A
typical value for this variable is "~".

This variable takes its initial value from the global variable
default_visible_virtual_lines at the time the buffer is created.

____________

See also:   visible_end_buffer, visible_newlines, visible_spaces, visible_tabs,
visible_virtual_spaces


ΓòÉΓòÉΓòÉ 15.20.28. visible_virtual_spaces ΓòÉΓòÉΓòÉ

visible_virtual_spaces   Primitive

Purpose: Defines appearance of virtual spaces on-screen.

____________

Type: str visible_virtual_spaces

____________

Description: Each window has a visible_virtual_spaces variable associated with
it.  The visible_virtual_spaces variable is a string displayed wherever virtual
spaces occur in the window.  By default, this string contains a space.  This
means that virtual spaces have the same appearance as "real" spaces. Changing
this string does not change the text stored in the file or the contents of the
buffer. Only the appearance on the screen is affected.

Virtual spaces may be given a special graphical representation by assigning a
single character or string of characters to this variable.  Normally, only one
character is assigned to this string.  A typical value for this variable is
"\xb0", which appears as a partially filled block.

This variable takes its initial value from the global variable
default_visible_virtual_spaces at the time the buffer is created.

____________

See also:   visible_end_buffer, visible_newlines, visible_spaces, visible_tabs,
visible_virtual_lines


ΓòÉΓòÉΓòÉ 15.20.29. window_first ΓòÉΓòÉΓòÉ

window_first  read-only,   Primitive

Purpose: Stores line number of the first line of text in a window.

____________

Type: int window_first

____________

Description: Each window has a window_first variable associated with it.  The
window_first variable contains the number of the first visible buffer line in
the window.

____________

See also:   window_height, window_margin


ΓòÉΓòÉΓòÉ 15.20.30. window_flags ΓòÉΓòÉΓòÉ

window_flags   Primitive

Purpose: Stores a number of window attributes as flags.

____________

Type: int window_flags

____________

Description:

Each window has a window_flags variable associated with it.  Individual bits of
window_flags are used by the editor to signify if the window has borders,
whether the window takes up the full screen or is an icon and so on.

The initial settings of this variable are obtained from the variable
default_window_flags at the time the window is created.  Therefore this
description of window_flags also applies to the variable default_window_flags.

You may elect to completely change the value of window_flags or modify just one
field of this variable.  When assigning a new value to window_flags select one
value for each field from the tables below, add them together and assign the
result to window_flags.

When modifying one element of window_flags while preserving the rest, use the
set_flag_bits() function to perform the bit manipulation for you. You will need
to supply to set_flag_bits() the appropriate field mask from the table above
and the desired field value from the tables below.

A series of descriptive labels representing field masks and field values have
been defined for your use.  The values associated with these labels are defined
in the source file WINDOWS.PEL.  Only the descriptive labels are listed in the
tables.

The window_flags variable is comprised of a number of subfields and TRUE/FALSE
or ON/OFF flags.  Here is a listing of the bits of window_flags and their
significance:

o WINDOW_ZOOM
o WINDOW_SYSTEM
o WINDOW_BORDERS
o WINDOW_SCROLLBARS
o WINDOW_TITLEBAR
o WINDOW_DISPLAY_FULL_FILENAME
o Useful combinations


ΓòÉΓòÉΓòÉ 15.20.30.1. WINDOW_ZOOM ΓòÉΓòÉΓòÉ

WINDOW_ZOOM (0x00000003)

The Zoom Status Field is comprised of the first two bits of the window flags
variable.  This tells whether the window is reduced to an icon, normal size or
expanded to fill the entire screen. Possible values and their meaning:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDescription                                  ΓöéVariable            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéThe window is an icon.                       ΓöéWINDOW_COLLAPSED    Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéThe window is its normal size.               ΓöéWINDOW_NORMAL       Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéThe window is expanded.                      ΓöéWINDOW_EXPANDED     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéThe window is invisible (not just covered).  ΓöéWINDOW_HIDDEN       Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.20.30.2. WINDOW_SYSTEM ΓòÉΓòÉΓòÉ

WINDOW_SYSTEM (0x00000004)

The System Window Flag identifies whether or not a window is a system window.
System windows differ from ordinary windows in that the functions that move
sequentially through the window list (next_window(), prev_window()) skip over
system windows by default.


ΓòÉΓòÉΓòÉ 15.20.30.3. WINDOW_BORDERS ΓòÉΓòÉΓòÉ

WINDOW_BORDERS (0x00000030)

The value in this field determines the type of border displayed for the window.
For a more complete description of these features, see the "Windowing" chapter
in Part One of this manual and the "Using a Mouse" chapter of the User's
Manual. The possible combinations and their field values appear below:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDescription              ΓöéVariable            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNo border                ΓöéWINDOW_NOBORDER     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNon sizing border        ΓöéWINDOW_NORM_BORDER  Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSizing border            ΓöéWINDOW_SIZE_BORDER  Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.20.30.4. WINDOW_SCROLLBARS ΓòÉΓòÉΓòÉ

WINDOW_SCROLLBARS (0x000000C0)

The value in this field determines if scrollbars are displayed for the window.
The possible combinations and their field values appear below:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDescription              ΓöéVariable            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéVertical Scroll Bar      ΓöéWINDOW_VERT_SB      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéHorizontal Scroll Bar    ΓöéWINDOW_HORIZ_SB     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.20.30.5. WINDOW_TITLEBAR ΓòÉΓòÉΓòÉ

WINDOW_TITLEBAR (0x00000F00)

The value in this field determines what is displayed on the title bar.  The
title bar can contain a system menu, minimize box, and/or a maximize box.  The
possible combinations and their field values appear below:

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDescription              ΓöéVariable            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéNo Title Bar             ΓöéWINDOW_NO_TITLE     Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéTitle bar                ΓöéWINDOW_TITLE        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMinimize box             ΓöéWINDOW_MIN_BOX      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMaximize box             ΓöéWINDOW_MAX_BOX      Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSystem menu              ΓöéWINDOW_SYS_MENU     Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.20.30.6. WINDOW_DISPLAY_FULL_FILENAME ΓòÉΓòÉΓòÉ

WINDOW_DISPLAY_FULL_FILENAME (0x00010000)

The value in this field determines if the fully specified filename is displayed
on the title bar.  If this bit is set then the fully qualified path name is
displayed on the title bar.  If this bit is not set then just the file name is
displayed on the title bar.


ΓòÉΓòÉΓòÉ 15.20.30.7. Useful combinations ΓòÉΓòÉΓòÉ

Useful combinations (0x00000F00)

The following table lists some predefined useful combinations of window_flags.

ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéDescription              ΓöéVariable            Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéMDI window               Γöé WINDOW_STANDARD_MDIΓöé
Γöé                         Γöé(0x00010FE1)        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéSDI window               Γöé WINDOW_STANDARD_SDIΓöé
Γöé                         Γöé(0x000100C2)        Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéPlain window             Γöé WINDOW_PLAIN       Γöé
Γöé                         Γöé(0x00010111)        Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ


ΓòÉΓòÉΓòÉ 15.20.31. window_height ΓòÉΓòÉΓòÉ

window_height  read-only,   Primitive

Purpose: Tells over-all height of the current window in lines.

____________

Type: int window_height

____________

Description: Each window has a window_height variable associated with it.  The
window_height variable indicates how many pixels are occupied by the window.
Only the size of the text display region of the window is included in this
variable.  The title bar and any scroll bars or borders are not included in the
measurement.

Along with the window_width variable, this variable defines the over-all
dimensions of the window. This variable is read-only and may not be modified by
the user or user-written functions.

____________

See also:  window_x0, window_y0, window_width


ΓòÉΓòÉΓòÉ 15.20.32. window_margin ΓòÉΓòÉΓòÉ

window_margin  read-only,   Primitive

Purpose: Tells the number of columns off-screen to the left.

____________

Type: int window_margin

____________

Description: Each window has a window_margin variable associated with it.  The
window_margin variable indicates how many columns of text have scrolled
out-of-sight to the left.  When the beginning of lines are visible
window_margin will be zero.

See also:  window_x0, window_y0, window_text_height, window_text_width()
window_height, window_width


ΓòÉΓòÉΓòÉ 15.20.33. window_name ΓòÉΓòÉΓòÉ

window_name   Primitive

Purpose:  Stores a name for display in a window's title bar.

____________

Type:    str window_name

____________

Description: The window_name variable holds the name of the current_window.
This variable can be set by the user and used in the next_window() function.
window_name is also used as the buffer filter in the next_buffer_mask()
function.  All of the packaged emulation modes use next_buffer_mask() to move
to the next buffer.

____________


ΓòÉΓòÉΓòÉ 15.20.34. window_page_offset ΓòÉΓòÉΓòÉ

window_page_offset   Primitive

Purpose: Cursor line position used when window is re-drawn.

____________

Type: int window_page_offset

____________

Description: Each window has a window_page_offset variable associated with it.
This variable indicates the line, relative to the center, on which the cursor
is placed after large vertical movements within the buffer.  Such movements
include jumps to distant line numbers, jumps to buffer extremities and other
motions which completely change the contents of the window.

The number contained in window_page_offset represents the number of lines from
the center line of the window to the line which contains the cursor.  Negative
numbers indicate a line above the center while positive numbers position the
cursor on a line below the center.

For example, if the value of window_page_offset is -3 the editor will position
the cursor three lines above the center line of the window.  The value 12 will
position the cursor twelve lines below the center line, if the window extends
down that far.

If the value for window_page_offset would place the cursor outside the limits
of the window, the cursor is placed on the last or first line of the window,
depending on whether the value is positive or negative.

The cursor column position is determined by the type of motion command executed
and the condition of the scroll_means_pan variable.  Usually this means that
the cursor will attempt to retains the same column position it occupied before
the move. The initial setting of this variable is obtained from the variable
default_window_page_offset at the time the window is created.

____________

Examples:

window_page_offset  = -999  # cursor at top
window_page_offset  = 0   # cursor at center
window_page_offset  = 999  # cursor at bottom


ΓòÉΓòÉΓòÉ 15.20.35. window_page_overlap ΓòÉΓòÉΓòÉ

window_page_overlap   Primitive

Purpose: Defines how many lines are retained after paging.

____________

Type: int window_page_overlap

____________

Description: Each window has a window_page_overlap variable associated with it.
The window_page_overlap variable stores the number of previously visible lines
that remain visible after a page_up() or page_down() is executed.  These "page"
functions scroll the contents of the window the window height less the amount
of this variable.

The initial setting of this variable is obtained from the variable
default_window_page_overlap at the time the window is created.

____________

See also:   page_down(), page_up()


ΓòÉΓòÉΓòÉ 15.20.36. window_text_height ΓòÉΓòÉΓòÉ

window_text_height  read-only,   Primitive

Purpose: Tells how many lines of text a window may contain.

____________

Type: int window_text_height

____________

Description: Each window has a window_text_height variable associated with it.
The window_text_height variable indicates how many lines of text may be shown
in the window.  Borders, scroll bars and titles, if any, are not included in
this measurement.

Along with the window_text_width() variable, this variable may be used to
determine the dimensions of the text in the window.

See also:  window_text_x0, window_text_y0, window_text_width()


ΓòÉΓòÉΓòÉ 15.20.37. window_text_width ΓòÉΓòÉΓòÉ

window_text_width read-only,   Primitive

Purpose: Tells how many columns of text a window contains.

____________

Type: int window_text_width

____________

Description: Each window has a window_text_width variable associated with it.
The window_text_width variable indicates how many columns of text can appear in
the window.  Borders are not included in this measurement.  In addition,
displaying line numbers reduces this measure.  Along with the
window_text_height variable, this variable may be used to determine the
dimensions of the text in the window.

See also:  window_text_x0, window_text_y0, window_text_height


ΓòÉΓòÉΓòÉ 15.20.38. window_text_x0 ΓòÉΓòÉΓòÉ

window_text_x0 read-only,   Primitive

Purpose: Tells the column offset of text in the window.

____________

Type: int window_text_x0

____________

Description: Each window has a window_text_x0 variable associated with it.  The
window_text_x0 variable tells the number of columns in the window precede the
window's text area.  Window borders and line numbers are not counted as window
text.  Together with window_text_y0, this variable defines the location of the
upper left-hand corner of the text area of the window.

____________

See also:  window_text_y0, window_text_height window_text_width()


ΓòÉΓòÉΓòÉ 15.20.39. window_text_y0 ΓòÉΓòÉΓòÉ

window_text_y0 read-only,   Primitive

Purpose: Tells the line offset of text in the window.

____________

Type: int window_text_y0

____________

Description: Each window has a window_text_y0 variable associated with it.  The
window_text_y0 variable tells how many lines in the window precede the text
area of the window.  This measure includes any window border, tab ruler or
title that appears above the text.  Together with window_text_x0, this variable
defines the location of the upper left- hand corner of the text area of the
window.

____________

See also:  window_text_x0, window_text_height window_text_width()


ΓòÉΓòÉΓòÉ 15.20.40. window_width ΓòÉΓòÉΓòÉ

window_width  read-only,   Primitive

Purpose: Tells how many columns the current window contains.

____________

Type: int window_width

____________

Description: Each window has a window_width variable associated with it.  The
window_width variable indicates how many columns of text are occupied by the
window. Any borders surrounding the window are included in this measurement.
Along with the window_height variable, this variable may be used to determine
the dimensions of the window.

This variable is read-only and may not be modified by the user or user-written
macros.  The width of a window must be modified using the frame_window()
function.

____________

See also:  window_x0, window_y0, window_height


ΓòÉΓòÉΓòÉ 15.20.41. window_x0 ΓòÉΓòÉΓòÉ

window_x0  read-only,   Primitive

Purpose: Tells the column offset of the window.

____________

Type: int window_x0

____________

Description: Each window has a window_x0 variable associated with it.  The
window_x0 variable tells the number of pixels to the left of the window on the
screen. Together with window_y0, this variable defines the location of the
lower left-hand corner of the window.

This variable is read-only and may not be modified by the user or user written
functions.  To change the position of the window, use the frame_window()
function.

____________

See also:  window_y0, window_height window_width


ΓòÉΓòÉΓòÉ 15.20.42. window_y0 ΓòÉΓòÉΓòÉ

window_y0  read-only,   Primitive

Purpose: Tells the line offset of the window.

____________

Type: int window_y0

____________

Description: Each window has a window_y0 variable associated with it.  The
window_y0 variable tells the number of pixels that precede the window on the
screen. Together with window_x0, this variable defines the location of the
upper left-hand corner of the window.

This variable is read-only and may not be modified by the user or user written
functions.  To change the position of the window, use the frame_window()
function.

____________

See also:  window_x0, window_height window_width


ΓòÉΓòÉΓòÉ 15.21. Word Processing ΓòÉΓòÉΓòÉ

default_auto_indent_mode
          Indicates if new lines are automatically indented.
default_wp_left_margin
          Sets left margin for use when word-wrap enabled.
default_wp_right_margin
          Sets right margin for use when word-wrap is enabled.
paragraph_pattern
          Define what delimits a paragraph.
sentence_pattern
          Define what delimits a sentence.
wp_left_margin
          Sets left margin for use when word-wrap enabled.
wp_right_margin
          Sets right margin for use when word-wrap is enabled.


ΓòÉΓòÉΓòÉ 15.21.1. default_auto_indent_mode ΓòÉΓòÉΓòÉ

default_auto_indent_mode   Primitive

Purpose: Indicates if new lines are automatically indented.

____________

Type:   int default_auto_indent_mode

____________

Description:

The default_auto_indent_mode variable contains the initial value of the
auto_indent_mode variable when a new buffer is created.

____________

See also:  auto_indent_mode


ΓòÉΓòÉΓòÉ 15.21.2. default_wp_left_margin ΓòÉΓòÉΓòÉ

default_wp_left_margin   Primitive

Purpose: Sets left margin for use when word-wrap enabled.

____________

Type:   int default_wp_left_margin

____________

Description:

The default_wp_left_margin variable contains the initial value of the
wp_left_margin variable when a new buffer is created.

____________

See also:  wp_left_margin


ΓòÉΓòÉΓòÉ 15.21.3. default_wp_right_margin ΓòÉΓòÉΓòÉ

default_wp_right_margin   Primitive

Purpose: Sets right margin for use when word-wrap is enabled.

____________

Type:   int default_wp_right_margin

____________

Description:

The default_wp_right_margin variable contains the initial value of the
wp_right_margin variable when a new buffer is created.

____________

See also:  wp_right_margin


ΓòÉΓòÉΓòÉ 15.21.4. paragraph_pattern ΓòÉΓòÉΓòÉ

paragraph_pattern   PEL

Purpose:  Define what delimits a paragraph.

____________

Type:    str paragraph_pattern

____________

Description: The paragraph_pattern variable defines what delimits a paragraph.
This variable is used in the paragraph motion functions.

____________


ΓòÉΓòÉΓòÉ 15.21.5. sentence_pattern ΓòÉΓòÉΓòÉ

sentence_pattern   PEL

Purpose:  Define what delimits a sentence.

____________

Type:    str sentence_pattern

____________

Description: The sentence_pattern variable defines what delimits a sentence.
This variable is used in the sentence motion functions.

____________


ΓòÉΓòÉΓòÉ 15.21.6. wp_left_margin ΓòÉΓòÉΓòÉ

wp_left_margin   Primitive

Purpose: Sets left margin for use when word-wrap enabled.

____________

Type: int wp_left_margin

____________

Description: Each edit buffer has a wp_left_margin variable associated with it.
When this variable is set to a value greater than zero, this value defines the
buffer column number which is to be preceded by a margin.  The columns to the
left of the named column are maintained as a margin by word- processing
functions while text to the right of this margin is subject to wrapping and
adjustment.

Text may be forcibly inserted in these margins, but if this is done, the text
is treated as part of the margin on subsequent reformatting.  In other words,
the text in the margin is not moved along with the rest of the text in the
paragraph.

Changing the value of this variable when word-wrap is enabled causes the entire
paragraph to be reformatted to conform to the new value.  This variable takes
its initial value from the global variable default_wp_left_margin at the time
the buffer is created.  Word-processing is enabled with the wp() function.

Word-wrap and word processing features of the editor are discussed in greater
detail in the "Word Processing" chapter in Part One of this manual.

____________

See also:   buffer_flags, wp_right_margin, wp()


ΓòÉΓòÉΓòÉ 15.21.7. wp_right_margin() ΓòÉΓòÉΓòÉ

wp_right_margin   Primitive

Purpose: Sets right margin for use when word-wrap is enabled.

____________

Type: int wp_right_margin

____________

Description: Each edit buffer has a wp_right_margin variable associated with
it.  This variable represents the column number beyond which text is not
allowed to extend when word-processing is enabled.  Text extending beyond this
limit is word-wrapped to the next line.  Word-processing is enabled with the
wp() function.

This variable takes its initial value from the global variable
default_wp_right_margin at the time the buffer is created.

Word-wrap and word processing features of the editor are discussed in greater
detail in the "Word Processing" chapter in Part One of this manual.

____________

See also:   buffer_flags, wp_left_margin


ΓòÉΓòÉΓòÉ 16. Trouble Shooting ΓòÉΓòÉΓòÉ

Refer to this section when you are having trouble in PREDITOR/2.  Listed below
are the areas where you may encounter a problem.  Find your problem in the list
and refer to that sectioin for the solution.  If your problem is not listed,
refer to the Technical Support section for information on how to contact us.

o Loading UNIX files
o Screen corruption
o Illegal variable name
o System Errors
o IBM WorkFrame/2 doesn't send errors
o Technical support


ΓòÉΓòÉΓòÉ 16.1. Technical support ΓòÉΓòÉΓòÉ

At Compuware, we strive to make our products and documentation the best in the
industry. Feedback from our customers helps us maintain our quality standards.

CompuServe Support

For the quickest response to your question,  access the Other Vendor section of
the CompuServe OS/2 Vendor Forum, GO OS2AVEN. Compuware provides unlimited
support through CompuServe.

Product Support Hotline

Customers will receive 90 days of free hotline support from Compuware's Product
Support Hotline.  Contact the hotline by calling 1-800-538-7822.

Please obtain the following information before placing your call:

 1. The version of PREDITOR/2 you are using.
 2. The version of OS/2 you are using.
 3. The title of the window or pop-up where the problem occurred and the steps
    taken before the problem occurred.
 4. The exact error message, if one was displayed.
 5. The PC system message displayed (if any).
This information helps us determine the cause of the problem as quickly as
possible.

Corporate Buyers  Compuware will also negotiate custom support plans for
corporate buyers.

PREDITOR/2 Product Support
Compuware Corporation
31440 Northwestern Highway
Farmington Hills, MI 48334-2564
1-800-538-7822


ΓòÉΓòÉΓòÉ 16.2. Loading UNIX files ΓòÉΓòÉΓòÉ

Problem: When I load a file it displays as one long line.

Solution: You have probably loaded a file which uses '\n' (which is the UNIX
standard) as the newline character. By default, the editor expects a '\r\n' as
a newline sequence. To fix this problem see the edit_unix_file_key(),
toggle_unix(), toggle_buffer_eol(), unix_edit(), or dos_edit() functions.


ΓòÉΓòÉΓòÉ 16.3. Screen corruption ΓòÉΓòÉΓòÉ

Problem:  After upgrading from version 2.0.1 or earlier my screen is not
drawing properly.

Solution: If you are upgrading from version 2.0.1 or earlier you may need to
reselect your screen and printer fonts the first time you run the editor after
installing.  You will only need to do this if you notice that your screen
display is not updating properly.


ΓòÉΓòÉΓòÉ 16.4. Illegal variable name ΓòÉΓòÉΓòÉ

Problem: I am programming in PEL and get the compiler message "Illegal variable
'XXX':it is a reserved function name".  I am not declaring a variable just
trying to call a function.

Solution: When calling functions from PEL programs you cannot have a space
between the function name and the open parenthesis.


ΓòÉΓòÉΓòÉ 16.5. IBM WorkFrame/2 doesn't send errors ΓòÉΓòÉΓòÉ

Problem: While using the IBM WorkFrame/2 support the editor is loaded when I
double click on an error but it doesn't position to the proper line.

Solution: Make sure IBM WorkFrame/2 support is enabled by supplying the -W
command line option when starting the editor from WorkFrame/2.  Also make sure
you have configured WorkFrame/2 properly by selecting the 'send errors to
editor' option in WF/2.


ΓòÉΓòÉΓòÉ 16.6. System Errors ΓòÉΓòÉΓòÉ

Problem: I recieve a system error message and the editor exits.

Solution:  Locate the cpe.msg file and contact Technical Support for
instructions.


ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ

Space that is not represented by a character in a buffer.