Computer Select (Limited Edition)

home *** CD-ROM | disk | FTP | other *** search

/ Computer Select (Limited Edition) / Computer Select.iso / dobbs / v17n06 / dflat.doc < prev next >

Wrap

Text File | 1992-03-28 | 50.5 KB | 1,346 lines

Window Classes: Window classes define the behavior of windows. Each class has its own unique reaction to messages. Classes derive from other classes. NORMAL base window for all window classes APPLICATION application window. has the menu (derived from NORMAL) TEXTBOX textbox. base window for listbox, editbox, etc. (derived from NORMAL) LISTBOX listbox. base window for menubar (derived from TEXTBOX) PICTUREBOX picturebox. a text box onto which you can draw lines (derived from TEXTBOX) EDITBOX editbox (derived from TEXTBOX) MENUBAR the application's menu bar (derived from NORMAL) POPDOWNMENU popdown menu (derived from LISTBOX) BUTTON command button in a dialog box (derived from TEXTBOX) SPINBUTTON spin button in a dialog box (derived from LISTBOX) COMBOBOX combination editbox/listbox (derived from EDITBOX) DIALOG dialog box. parent to editbox, button, listbox, etc. (derived from NORMAL) ERRORBOX for displaying an error message (derived from DIALOG) MESSAGEBOX for displaying a message (derived from DIALOG) HELPBOX help window (derived from DIALOG) TEXT static text on a dialog box (derived from TEXTBOX) RADIOBUTTON radio button on a dialog box (derived from TEXTBOX) CHECKBOX check box on a dialog box (derived from TEXTBOX) STATUSBAR status bar at the bottom of application window (derived from TEXTBOX) D-Flat Window Class Tree ┌─────────────────────────────────────────────┐ │ │ │ NORMAL │ │ │ │ │ ├── APPLICATION │ │ │ │ │ ├── MENUBAR │ │ │ │ │ ├── TEXTBOX │ │ │ │ │ │ │ ├── LISTBOX │ │ │ │ │ │ │ │ │ ├──── POPDOWNMENU │ │ │ │ │ │ │ │ │ └──── SPINBUTTON │ │ │ │ │ │ │ ├── EDITBOX │ │ │ │ │ │ │ │ │ └──── COMBOBOX │ │ │ │ │ │ │ ├── PICTUREBOX │ │ │ │ │ │ │ ├── STATUSBAR │ │ │ │ │ │ │ ├── TEXT │ │ │ │ │ │ │ ├── BUTTON │ │ │ │ │ │ │ ├── RADIOBUTTON │ │ │ │ │ │ │ └── CHECKBOX │ │ │ │ │ └── DIALOG │ │ │ │ │ ├── ERRORBOX │ │ │ │ │ ├── MESSAGEBOX │ │ │ │ │ └── HELPBOX │ │ │ └─────────────────────────────────────────────┘ Window Attributes: Every window has an attribute word that defines some of its appearance and behavior. The following values are bitwise flags that OR together to make a window's attributes. You can establish default attributes for a window's class, add additional attributes when you create the window, and use the AddAttribute, ClearAttribute, and TestAttribute macros to change and test a window's attributes. SHADOW has a shadow MOVEABLE can move the window with mouse or cursor SIZEABLE can resize the window with mouse or cursor HASMENUBAR has a menubar (an application window) VSCROLLBAR has a vertical scroll bar HSCROLLBAR has a horizontal scroll bar VISIBLE is visible SAVESELF saves its own video memory TITLEBAR has a title bar CONTROLBOX has a control box and control menu MINMAXBOX has a min/max box NOCLIP is not clipped to its parent's borders READONLY is a readonly textbox MULTILINE is a multiline editbox or listbox HASBORDER has a border HASSTATUSBAR has a statusbar (application window only) Messages: A D-Flat program is message-driven. You initiate message processing with the init_messages function, create a window with the CreateWindow function, and go into the message dispatching loop with the dispatch_message function. A window can have a window-processing function. When the user causes events to occur by pressing keys and using the mouse, D-Flat sends messages to the window's function. That function can send messages to itself and other windows with the SendMessage and PostMessage functions. Windows are declared as members of a class. Every class has a default window-processing function. If you do not provide one for an instance of a window class, the default one receives messages for the window. Your custom window-processing function--if one exists--should chain to the default window-processing function for the blass by calling the DefaultWndProc function. There are five things a window-processing function can do with a message: - ignore it and let the D-Flat default processing occur. - suppress it by returning without chaining to the default window-processing function for the window class. - chain to the default window-processing function and then do some additional processing. - do some preliminary processing and then chain to the default window-processing function. - do all the processing of the message and then return without chaining to the default window-processing function for the window class. Following are the messages that an application program would use. There are other messages, but they are used by D-Flat only. Process Communication Messages START start message processing (not used now) Sent: P1: P2: Returns: STOP stop message processing Sent: by application window to NULL to stop message dispatch loop P1: P2: Returns: COMMAND send a command to a window Sent: to send command P1: command code (commands.h) P2: additional data (command-dependent) If the command code is a menu selection, P2 is the position of the selection on the menu (1,2,...) If the command code is a dialog box control, P2 is ENTERFOCUS when the command gets the focus, LEAVEFOCUS when the command loses the focus, and 0 when the user executes the control's command, e.g. presses a button. Returns: Nothing if sent by PostCommand Command-dependent value if sent by SendCommand Window Management Messages CREATE_WINDOW create a window Sent: by DFLAT to new window after window is created P1: P2: Returns: SHOW_WINDOW show a window Sent: by the app to the window to display the window P1: P2: Returns: HIDE_WINDOW hide a window Sent: by the app to the window to hide the window P1: P2: Returns: CLOSE_WINDOW delete a window Sent: by the app to destroy a window P1: P2: Returns: SETFOCUS set and clear the focus Sent: by D-Flat or the app to set or release the focus P1: true = set, false = release P2: Returns: PAINT paint the window's data space Sent: to paint the client area of a window P1: address of RECT relative to window (0/0 = upper left) to paint or 0 to paint entire client area P2: True to make non-focus window paint without clipping Returns: BORDER paint the window's border Sent: to paint a window's border P1: address of RECT relative to window (0/0 = upper left) to paint or 0 to paint entire border P2: Returns: FALSE to suppress D-Flat title display (e.g. the window displays its own border) TITLE display the window's title Sent: by D-Flat when it is about to display a window's title P1: address of RECT relative to window (0/0 = upper left) to paint or 0 to paint entire title P2: Returns: FALSE to suppress D-Flat title display (e.g. the window displays its own title) MOVE move the window Sent: to move a window P1: new left coordinate P2: new upper coordinate Returns: SIZE change the window's size Sent: to resize a window P1: new right coordinate P2: new lower coordinate Returns: MAXIMIZE maximize the window Sent: to maximize a window within its parent's client area P1: P2: Returns: MINIMIZE minimize the window Sent: to minimize a window to an icon P1: P2: Returns: RESTORE restore the window Sent: to restore a window to its position and size prior to the maximize or minimize operation P1: P2: Returns: INSIDE_WINDOW test x/y inside a window Sent: to test to see if coordinates are inside a window P1: x P2: y Returns: true or false Clock Messages CLOCKTICK the clock ticked Sent: every second to a window that has captured the clock P1: segment of time display string P2: offset of time display string Returns: CAPTURE_CLOCK capture clock into a window Sent: to capture the clock P1: P2: Returns: RELEASE_CLOCK release clock to the system Sent: to release the captured clock P1: P2: Returns: Keyboard and Screen Messages KEYBOARD key was pressed Sent: when key is pressed. sent to the window that has the focus P1: keystroke P2: shift key mask Returns: CAPTURE_KEYBOARD capture keyboard into a window Sent: by window to itself to capture the keyboard regardless of focus P1: P2: Returns: RELEASE_KEYBOARD release keyboard to system Sent: by window to itelf to release the captured keyboard P1: P2: Returns: KEYBOARD_CURSOR position the keyboard cursor Sent: to position the keyboard cursor P1: x (if sent by window, 0 = left client area) P2: y (if sent by window, 0 = top client area) if sent with NULL, x/y are relative to the screen Returns: CURRENT_KEYBOARD_CURSOR read the cursor position Sent: to retrieve the cursor position P1: x (relative to the screen) P2: y (relative to the screen) Returns: HIDE_CURSOR hide the keyboard cursor Sent: to hide the keyboard cursor P1: P2: Returns: SHOW_CURSOR display the keyboard cursor Sent: to display the keyboard cursor P1: P2: Returns: SAVE_CURSOR save the cursor's configuration Sent: to save the keyboard cursor's current configuration P1: P2: Returns: RESTORE_CURSOR restore the saved cursor Sent: to restore a keyboard cursor's saved configuration P1: P2: Returns: SHIFT_CHANGED the shift status changed Sent: to in-focus window when the user presses or releases shift, alt, or ctrl key P1: BIOS shift key mask P2: Returns: WAITKEYBOARD wait for key release Sent: to wait for a keypress release P1: P2: Returns: Mouse Messages RESET_MOUSE reset the mouse Sent: to reset the mouse to the current screen configuration P1: P2: Returns: MOUSE_TRAVEL set the mouse's travel Sent: to limit the mouse travel to a screen rectangle P1: address of a RECT P2: Returns: MOUSE_INSTALLED test for mouse installed Sent: to see if the mouse is installed P1: P2: Returns: true or false RIGHT_BUTTON right button pressed Sent: to window when the user presses the right button (sent only when mouse cursor is within the window or the window has captured the mouse) P1: x P2: y Returns: LEFT_BUTTON left button pressed Sent: to window when the user presses the left button (sent only when mouse cursor is within the window or the window has captured the mouse) P1: x P2: y Returns: DOUBLE_CLICK left button doubleclicked Sent: to window when the user double-clicks the left button (sent only when mouse cursor is within the window or the window has captured the mouse) (a LEFT_BUTTON message will have preceded this one) P1: x P2: y Returns: MOUSE_MOVED mouse changed position Sent: to window when the mouse has moved (sent only when mouse cursor is within the window or the window has captured the mouse) P1: x P2: y Returns: BUTTON_RELEASED mouse button released Sent: to window when user releases mouse button (sent only when mouse cursor is within the window or the window has captured the mouse) P1: x P2: y Returns: CURRENT_MOUSE_CURSOR get mouse position Sent: to determine the current mouse position P1: address of x P2: address of y Returns: MOUSE_CURSOR set mouse position Sent: to set the current mouse position P1: x P2: y Returns: SHOW_MOUSE make mouse cursor visible Sent: to display the mouse cursor P1: P2: Returns: HIDE_MOUSE hide mouse cursor Sent: to hide the mouse cursor P1: P2: Returns: WAITMOUSE wait until button released Sent: to wait until the user releases the mouse button P1: P2: Returns: TESTMOUSE test any mouse button pressed Sent: to see if either mouse button is pressed P1: P2: Returns: true or false CAPTURE_MOUSE capture mouse into a window Sent: by/to a window to capture all mouse activity regardless of whether it occurs inside this window P1: P2: Returns: RELEASE_MOUSE release the mouse to system Sent: release a captured mouse P1: P2: Returns: Text Box Messages ADDTEXT add text to the text box Sent: to append a line of text to the text box P1: address of null-terminated string (textbox makes its own copy. string can go out of scope.) P2: Returns: DELETETEXT delete line of text from the text box Sent: to append a line of text to the text box P1: line number relative to zero P2: Returns: INSERTTEXT insert line of text into the text box Sent: to append a line of text to the text box P1: address of null-terminated string (textbox makes its own copy. string can go out of scope.) P2: line number relative to zero that will follow new line. Returns: CLEARTEXT clear the text box Sent: clear all text from the text box P1: P2: Returns: SETTEXT set text buffer contents Sent: To set text buffer to caller's text. P1: address of text buffer (lines are terminated by \n without \0) (textbox makes its own copy. string can go out of scope.) P2: length of text buffer Returns: SCROLL vertical scroll of text box Sent: to scroll a text window vertically one line P1: true = scroll up, false = scroll down P2: Returns: HORIZSCROLL horizontal scroll of text box Sent: to scroll a text window horizontally one column P1: true = scroll left, false = scroll right P2: Returns: SCROLLPAGE vertical scroll of text box 1 page Sent: to scroll a text window vertically one page P1: true = scroll up, false = scroll down P2: Returns: HORIZSCROLLPAGE horizontal scroll of text box 1 page Sent: to scroll a text window horizontally one page P1: true = scroll left, false = scroll right P2: Returns: SCROLLDOC document scroll of text box Sent: to scroll a text window to beginning/end of document P1: true = scroll to beginning, false = scroll to end P2: Returns: Edit Box Messages GETTEXT get text from an edit box Sent: Get the line of text from a single-line editbox P1: address of receiving buffer P2: max length to copy Returns: SETTEXTLENGTH set maximum text length in an edit box Sent: to set the maximum number of characters that an editbox may hold in its buffer. P1: maximum character count P2: Returns: Application Window Messages ADDSTATUS write text to the status bar Sent: to write to or clear status bar text area P1: address of text (null-terminated string) or NULL to clear P2: Returns: List Box Messages LB_SELECTION list box selection Sent: sent by list box to self and to parent (if parent is not a simple LISTBOX window) when user moves to an entry on the list box. P1: selection number: 0, 1, ... P2: if multi-line selection listbox, shift status mask if not, true = selection was same as choice (e.g. mouse) Returns: LB_CHOOSE list box choice Sent: sent to parent of list box when user chooses an item from the list box P1: selection number: 0, 1, ... P2: Returns: LB_CURRENTSELECTION return the current selection Sent: To get the current selection number (where the listbox cursor is positioned) P1: P2: Returns: selection number: 0, 1, ... LB_GETTEXT return the text of selection Sent: To get a copy of the text at a specified line P1: Address of string to receive copy of text P2: Line number: 0, 1, ... Returns: LB_SETSELECTION sets the listbox selection Sent: To change where the listbox cursor points P1: Line number: 0, 1, ... P2: Returns: Picture Box Messages DRAWVECTOR Draws a vector Sent: To draw a vector in the window's client area P1: address of RECT that describes the vector relative to the window's client area (either lf = rt [vertical vector] or tp = bt [horizontal vector]) P2: Returns: DRAWBOX Draws a box Sent: To draw a box in the window's client area P1: address of RECT that describes the box relative to the window's client area P2: Returns: DRAWBAR Draws a barchart bar Sent: To draw a bar in the window's client area P1: address of RECT that describes the bar relative to the window's client area (either lf = rt [vertical vector] or tp = bt [horizontal vector]) P2: one of these: SOLIDBAR, HEAVYBAR, CROSSBAR, LIGHTBAR (4 different bar textures) Returns: ===================================================== API Functions & Macros: These are functions and macros defined for use by applications programs. There are many others defined in the header files. These others are for D-Flat to use, and programmers need not be concerned about them except as an expression of their curiosity about how D-Flat works. (Note: These specifications are not in any orderly sequence yet.) ------------------------------------------------------------------- void init_messages(void) Call this function first to initialize message processing. Continue only if the function returns a true value. Otherwise, terminate the processing of your program. A false return occurs from a longjmp that is executed when D-Flat attempts to allocate memory that is not available. ------------------------------------------------------------------- WINDOW CreateWindow( CLASS class, /* class of this window */ char *ttl, /* title or NULL */ int left, int top, /* upper left coordinates */ int height, int width, /* dimensions */ void *extension, /* pointer to additional data */ WINDOW parent, /* parent of this window */ int (*wndproc)(struct window *,MESSAGE,PARAM,PARAM), int attrib) /* window attribute */ This function creates a window. It returns the WINDOW handle that mesages and functions use to identify the window. ------------------------------------------------------------------- void PostMessage(WINDOW wnd, MESSAGE msg, PARAM p1, PARAM p2) Post a message to a window. The window will receive the message in turn during the message-dispatching loop. ------------------------------------------------------------------- int SendMessage(WINDOW wnd, MESSAGE msg, PARAM p1, PARAM p2) Send a message to a window. The window will receive the message immediately. Control returns to the sender after the window has processed the message. The window can return an integer value. This function can send system messages to NULL. System messages are ones that D-Flat processes without regard to a particular window. ------------------------------------------------------------------- int dispatch_message(void) The message dispatching loop. After opening the first window (usually the applications window), continue to call this function until it returns a FALSE value. ------------------------------------------------------------------- void handshake(void) This function dispatches messages without allowing any keyboard or click events to pass through. You use it to allow the clock to run or the watch icon to move during a lengthy process without allowing anything to execute a command that might interfere with what your program is doing. ------------------------------------------------------------------- int TestCriticalError(void) ------------------------------------------------------------------- int DefaultWndProc(WINDOW wnd, MESSAGE msg, PARAM p1, PARAM p2) Call this from a window-processing function to chain to the default window-processing function for the window's class. ------------------------------------------------------------------- int BaseWndProc(CLASS class, WINDOW wnd, MESSAGE msg, PARAM p1, PARAM p2) Call this from the window-processing function of a derived window class to chain to the window-processing function of the base window's class. ------------------------------------------------------------------- int WindowHeight(WINDOW wnd) int WindowWidth(WINDOW wnd) These functions return the window's height and width. ------------------------------------------------------------------- int ClientWidth(WINDOW wnd) int ClientHeight(WINDOW wnd) These functions return the height and width of the window's client area. ------------------------------------------------------------------- int GetTop(WINDOW wnd) int GetBottom(WINDOW wnd) int GetLeft(WINDOW wnd) int GetRight(WINDOW wnd) These functions return the screen coordinates of the four corners of the window. ------------------------------------------------------------------- int GetClientTop(WINDOW wnd) int GetClientBottom(WINDOW wnd) int GetClientLeft(WINDOW wnd) int GetClientRight(WINDOW wnd) These functions return the screen coordinates of the four corners of the window's client area. ------------------------------------------------------------------- WINDOW GetParent(WINDOW wnd) Returns the parent of the window or NULL if the window has no parent. ------------------------------------------------------------------- WINDOW GetFirstChild(WINDOW pwnd) Returns the first child of a parent window or NULL if the window has no children. ------------------------------------------------------------------- WINDOW GetNextChild(WINDOW pwnd, WINDOW cwnd) Call this function repetitively after GetFirstChild. It returns the next child window after the one specified in the second parameter. If there are no more children, the function returns NULL. ------------------------------------------------------------------- WINDOW GetLastChild(WINDOW pwnd) Returns the last child of a p`rent window or NULL if the window has no children. ------------------------------------------------------------------- WINDOW GetPrevChild(WINDOW pwnd, WINDOW wnd) Call this function repetitively after GetLastChild. It returns the previous child window before the one specified in the second parameter. If there are no more children, the function returns NULL. ------------------------------------------------------------------- int CharInView(WINDOW wnd, int x, int y) Returns true if the x/y character position, relative to the window, is in view (not clipped at the border of a parent window or the screen. ------------------------------------------------------------------- int TopBorderAdj(WINDOW wnd) Returns the value to add to a y coordinate of the window's client area to make it relative to the window top. ------------------------------------------------------------------- int BorderAdj(WINDOW wnd) Returns the value to add to an x coordinate relative to the window's client area to make it relative to the window's left edge. ------------------------------------------------------------------- char *GetTitle(WINDOW wnd) Returns the address of a window's title, or NULL if the window has no title. ------------------------------------------------------------------- void AddTitle(WINDOW wnd, char *title) Adds or changes the title to an existing window. ------------------------------------------------------------------- CLASS GetClass(WINDOW wnd) Returns the class of the window. ------------------------------------------------------------------- int GetAttribute(WINDOW wnd) Returns the attribute word of a window. ------------------------------------------------------------------- void AddAttribute(WINDOW wnd, int attrib) Adds one or more attributes to a window. OR the attribute values together. ------------------------------------------------------------------- void ClearAttribute(WINDOW wnd, int attrib) Clears one or more attributes from a window. OR the attribute values together. ------------------------------------------------------------------- int TestAttribute(WINDOW wnd, int attrib) Tests one or more attributes in a window. Returns true if any of them are set. OR the attribute values together. ------------------------------------------------------------------- int isVisible(WINDOW wnd) Returns true if the window is visible. ------------------------------------------------------------------- char *GetText(WINDOW wnd) Returns the address of the text buffer for a TEXTBOX or derived window class. ------------------------------------------------------------------- int GetTextLines(WINDOW wnd) Returns the number of text lines in a TEXTBOX or derived window class. ------------------------------------------------------------------- char *TextLine(WINDOW wnd, int line) Returns the address of a specified line of text (0, 1, ...) in a TEXTBOX or derived class. ------------------------------------------------------------------- WINDOW inWindow(WINDOW wnd, int x, int y) Returns the WINDOW handle of the window that x/y are in or NULL if x/y is outside of any window. Send NULL for wnd to search all windows. Send a window handle to search only that window's children. ------------------------------------------------------------------- int isActive(MENU *mnu, int command) Returns true if the command (commands.h) on the menu is active (enabled). ------------------------------------------------------------------- char *GetCommandText(MBAR *mn, int cmd) Returns the address of a menu command's title text. ------------------------------------------------------------------- void ActivateCommand(MENU *mnu, int command) void DeactivateCommand(MENU *mnu, int command) Activate (enable) or deactivate (disable) a command (commands.h) on a menu. ------------------------------------------------------------------- int GetCommandToggle(MENU *mnu, int command) void SetCommandToggle(MENU *mnu, int command) void ClearCommandToggle(MENU *mnu, int command) void InvertCommandToggle(MENU *mnu, int command) Some menu commands are toggles rather than executors of processes. Examples are the Insert and Word wrap commands on the Options menu. These functions get, set, clear, and invert the toggle setting for a specified command on a specified menu. ------------------------------------------------------------------- int ItemSelected(WINDOW wnd, int line) This function returns true if the specified item (0, 1, ...) on a multiple-line selection listbox is selected. ------------------------------------------------------------------- int DialogBox( WINDOW wnd, /* parent window of the dialog box */ DBOX *db, /* address of dialog box definition array */ int Modal, /* trus if it is a modal dialog box */ int (*wndproc)(struct window *, MESSAGE, PARAM, PARAM) /* the window processing function or NULL */ ) This function executes a dialog box. If it is a modal dialog box, the function does not return until the user completes the dialog box. The return value will be true if the user has selected OK and false if the user has selected Cancel on the dialog box. If the dialog box is modeless, the function returns immediately, and the user can select other things from the screen while the dialog box is still active. ------------------------------------------------------------------- WINDOW ControlWindow(DBOX *db, enum commands cmd) This function returns the WINDOW handle of the control specified by the cmd parameter. ------------------------------------------------------------------- int DlgOpenFile(char *filespec, char *filename) This function operates the Open File dialog box. The filespec pointer points to a default file path specification that the dialog box uses to display files, for example, *.DOC. If the function returns true, the space pointed to by the filename pointer will contain the path and filename selected by the user to be read. ------------------------------------------------------------------- int DlgSaveAs(char *filename) This function operates the Save As dialog box. If the function returns true, the space pointed to by the filename pointer will contain the path and filename selected by the user where the file will be written. ------------------------------------------------------------------- void MessageBox(char *title, char *message) void CancelBox(wnd, char *message) void ErrorMessage(char *message) int TestErrorMessage(char *message) int YesNoBox(char *question) WINDOW MomentaryMessage(char *message) These functions display generic message boxes. The message text is one null-terminated string with newlines (\n) to indicate where lines are to be broken. The size of the boxes adjusts to the width of the longest line and the number of lines of text. A message may have no more lines of text than will fit into the largest window that the screen can display. You must account for the window's border's and the presence at the bottom of one or more command buttons. The MessageBox function displays a message in a window with a title provided by the caller. The window contains the message and an OK command button. The CancelBox function displays a message in a window with a "Wait..." title. The window contains the message and a Cancel command button. If the user presses the Cancel button before the program closes the window, the COMMAND, ID_CANCEL message is sent to the parent window. The ErrorMessage function displays the message in an error box window with an OK command button. The TestErrorMessage function is an error message with OK and Cancel command buttons. The function returns true if the user selects OK or presses Enter and false if the user selects Cancel or presses Esc. The YesNoBox function displays the message with Yes and No command buttons. The function returns true if the user selects Yes or presses Enter and false if the user selects No or presses Esc. The MomentaryMessage function displays a message box and returns its WINDOW handle. The caller must close the window. The purpose of this function is to allow you to display a message while some time consuming process is underway and then erase the message after the process is done but without any action required from the user. ------------------------------------------------------------------- int InputBox(WINDOW wnd, char *ttl, char *msg, char *text, int len) This function executes a generic one-line user input dialog box. The wnd parameter is the parent window of the dialog box. The ttl parameter points to a title string for the dialog box. The msg parameter points to a prompting text message. The text parameter points to the string that will receive the user's input. The len parameter is the length of the input string not including the null terminator. The function returns a true value if the user chooses the OK command button and false if the user selects Cancel. ------------------------------------------------------------------- WINDOW SliderBox(int len, char *ttl, char *msg) This function displays a dialog box with the specified title and message, a slider bar of the specified length, and a Cancel button. The slider bar displays a percent value. You use the slider box to display feedback to the user when the program is doing a time-consuming task, such as printing a file. Periodically, through your process, you send a PAINT message to the window handle that the SliderBox function returns. The second parameter is the new percent value. When you have sent 100, the slider dialog box closes itself. If the user chooses the Cancel command on the dialog box, your next PAINT message returns FALSE. Otherwise it returns TRUE. ------------------------------------------------------------------- int RadioButtonSetting(DBOX *db, enum commands cmd) This function returns true if the specified command on the specified dialog box is a pressed radio button. ------------------------------------------------------------------- void EnableButton(DBOX *db, enum commands cmd) This function enables a command button on a dialog box. command buttons are initially enabled when the dialog box is first opened. ------------------------------------------------------------------- void DisableButton(DBOX *db, enum commands cmd) This function disables a command button on a dialog box. command buttons are initially enabled when the dialog box is first opened. ------------------------------------------------------------------- void PushRadioButton(DBOX *db, enum commands cmd) This function presses the specified radio button command on the specified dialog box. ------------------------------------------------------------------- void PutItemText(WINDOW wnd, enum commands cmd, char *text) This function appends a line of text to a TEXT, TEXTBOX, EDITBOX, LISTBOX, SPINBUTTON, or COMBOBOX control window in a dialog box. The wnd parameter is the WINDOW handle of the dialog box. The cmd parameter specifies the command associated with the control item. The text parameter points to the text to be added. The control window makes its own copy of the text, so the caller's copy can go out of scope. If the control window is a COMBOBOX, TEXTBOX, or EDITBOX window, you must send a PAINT message to the control window so that the new text will display. You must call this function while the dialog box is active. That means that if the dialog box is modal, you must call this function from within a custom window processing function that you supply when you call DialogBox. ------------------------------------------------------------------- void PutComboListText(WINDOW wnd, enum commands cmd, char *text) This function appends a line of text to the LISTBOX of a COMBOBOX control window in a dialog box. The wnd parameter is the WINDOW handle of the dialog box. The cmd parameter specifies the command associated with the combo box. The text parameter points to the text to be added. The control window makes its own copy of the text, so the caller's copy can go out of scope. You must call this function while the dialog box is active. That means that if the dialog box is modal, you must call this function from within a custom window processing function that you supply when you call DialogBox. ------------------------------------------------------------------- void GetItemText(WINDOW wnd, enum commands cmd, char *text, int length) This function copies the text from a TEXT, TEXTBOX, COMBOBOX, or EDITBOX control window in a dialog box. The wnd parameter is the WINDOW handle of the dialog box. The cmd parameter specifies the command associated with the control item. The text parameter points to the caller's buffer where the text will be copied. The length parameter specifies the maximum number of characters to copy. You must call this function while the dialog box is active. That means that if the dialog box is modal, you must call this function from within a custom window processing function that you supply when you call DialogBox. ------------------------------------------------------------------- char *GetEditBoxText(DBOX *db, enum commands cmd) This function returns a pointer to the text associated with an editbox control in a dialog box. You can call it after the dialog box has completed processing. The buffer is on the heap. Do not free it. Instead, call SetEditBoxText with a NULL pointer. If the text has not changed since it was initialized, this function returns NULL. ------------------------------------------------------------------- char *GetComboBoxText(DBOX *db, enum commands cmd) This function returns a pointer to the text associated with an combo box control in a dialog box. You can call it after the dialog box has completed processing. The buffer is on the heap. Do not free it. Instead, call SetEditBoxText with a NULL pointer. If the text has not changed since it was initialized, this function returns NULL. ------------------------------------------------------------------- void SetEditBoxText(DBOX *db, enum commands cmd, char *text) This function sets the text of a dialog box editbox. You can call this function before or while the dialog box is open. The dialog box makes it own copy on the heap, so your text can go out of scope. ------------------------------------------------------------------- void SetComboBoxText(DBOX *db, enum commands cmd, char *text) This function sets the text of a dialog box combo box. You can call this function before or while the dialog box is open. The dialog box makes it own copy on the heap, so your text can go out of scope. ------------------------------------------------------------------- char *GetDlgText(DBOX *db, enum commands cmd, char *text) Similar to GetEditBoxText except that it works with text controls. ------------------------------------------------------------------- char *SetDlgText(DBOX *db, enum commands cmd, char *text) Similar to SetEditBoxText except that it works with text controls. ------------------------------------------------------------------- char *GetDlgTextBox(DBOX *db, enum commands cmd, char *text) Similar to GetEditBoxText except that it works with textbox controls. ------------------------------------------------------------------- char *SetDlgTextBox(DBOX *db, enum commands cmd, char *text) Similar to SetEditBoxText except that it works with textbox controls. ------------------------------------------------------------------- void SetCheckBox(DBOX *db, enum commands cmd) void ClearCheckBox(DBOX *db, enum commands cmd) int CheckBoxSetting(DBOX *db, enum commands cmd) These functions set, clear, and test the setting of a specified check box control item on a dialog box. They are valid only when the dialog box is not active. ------------------------------------------------------------------- void SetDlgTitle(DBOX *db, char *ttl) This function changes the specified dialog box's title. ------------------------------------------------------------------- void LoadHelpFile(char *expath); This function loads the help file named by the DFLAT_APPLICATION global constant with the .HLP file extension. The expath parameter points to the DOS path where the file can be found. Call this function at the beginning of an application program. ------------------------------------------------------------------- void UnLoadHelpFile(void); Call this function at the end of a D-Flat application to free the memory used by a help file. ------------------------------------------------------------------- void SearchText(WINDOW wnd) Opens a dialog box for the user to enter a search string. Searches the wnd TEXTBOX for a match on the string. ------------------------------------------------------------------- void ReplaceText(WINDOW wnd) Opens a dialog box for the user to enter search and replacement strings. Searches the wnd TEXTBOX for a match on the string and replaces it if found. The dialog box includes an option to replace all matches. ------------------------------------------------------------------- void SearchNext(WINDOW wnd) Assumes that a previous SearchText call has found a match. Searches for the next match of the same string in the specified EDITBOX window. ------------------------------------------------------------------- void WriteTextLine(WINDOW wnd, RECT *rcc, int y, int reverse) This function displays a text line from a TEXTBOX or derived window class. The text has already been added to the window with ADDTEXT, etc. The y parameter specifies which line (0, 1, ...) relative to the window's text buffer to display. If the specified line is not in view, the function does nothing. If the reverse parameter is true, the line displays in the reverse-video colors of the window. The rcc RECT pointer is usually NULL for applications calls. It points to a rectangle relative to the window outside of which displays will not occur. ------------------------------------------------------------------- void PutWindowLine(WINDOW wnd, void *s, int x, int y) This function writes a line of text to a window. The x and y coordinates point to the first character in the window's client area where the line is to be written. The text must be null-terminated. This function clips the line if it goes beyond the window or the screen. The function clips the line if it goes outside the borders of the window's parent. If other windows overlap the target window, the text is clipped. Do not use negative values in x or y. You can assign color values to the global variables foreground and background to affect the color of the line's display. ------------------------------------------------------------------- void PutWindowChar(WINDOW wnd, int c, int x, int y) This function writes the character c to a window. The x and y coordinates are relative to the window's client area. The function performs clipping. If the character is beyond the window's or the screen's borders it is not written. If the window does not have the NOCLIP attribute, the character is not written if its coordinates are beyond the margins of its parent window (if the window has a parent). If other windows overlap the target window, the text is clipped. Do not use negative values in x or y. You can assign color values to the global variables foreground and background to affect the color of the character's display. ------------------------------------------------------------------- void DrawVector(WINDOW wnd, int x, int y, int len, int hv) Draw a horizontal vector in a picture box. x and y are character coordinates relative to the starting position of the vector. len is the length. hv is TRUE for a horizontal vector and FALSE for a vertical vector. Sends a DRAWVECTOR message to the window. Send a PAINT message to the window to display the vectors. ------------------------------------------------------------------- void DrawBox(WINDOW wnd, int x, int y, int ht, int wd) Draw a box in a picture box. x and y are character coordinates relative to the upper left corner of the box. ht and wd are the height and width of the box. Sends a DRAWBOX message to the window. Send a PAINT message to the window to display the box. ------------------------------------------------------------------- void DrawBar(WINDOW wnd, enum VectTypes vt, int x, int y, int len, int hv) Draw a graph bar in a picture box. vt is one of the following values to specify the character box used to display the bar: SOLIDBAR, HEAVYBAR, CROSSBAR, LIGHTBAR. x and y are character coordinates relative to the starting position of the bar. len is the length. hv is TRUE for a horizontal bar and FALSE for a vertical bar. Sends a DRAWBAR message to the window. Send a PAINT message to the window to display the bars. ------------------------------------------------------------------- void WindowClientColor(WINDOW wnd, int fg, int bg) Changes the window client space's foreground and background colors. ------------------------------------------------------------------- void WindowReverseColor(WINDOW wnd, int fg, int bg) Changes the window's foreground and background reverse colors, which are used to display such things as selected text blocks. ------------------------------------------------------------------- void WindowFrameColor(WINDOW wnd, int fg, int bg) Changes the window's foreground and background frame colors. ------------------------------------------------------------------- void WindowHighlightColor(WINDOW wnd, int fg, int bg) Changes the window's foreground and background highlight colors, which are used to display highlighted items such as menu selector bars. ------------------------------------------------------------------- void MarkTextBlock(WINDOW wnd, int BegLine, int BegCol, int EndLine, int EndCol) Marks a block in the specified TEXTBOX window. ------------------------------------------------------------------- void ClearTextBlock(WINDOW wnd) Unmarks a marked block in the specified TEXTBOX window. ------------------------------------------------------------------- void CopyToClipboard(WINDOW wnd) Copies the marked block from the WINDOW into the Clipboard. ------------------------------------------------------------------- void CopyTextToClipboard(char *string) Copies a null-terminated string into the Clipboard. ------------------------------------------------------------------- void PasteFromClipboard(WINDOW wnd) Pastes the Clipboard's contents into the specified EDITBOX window at the current cursor location. ------------------------------------------------------------------- void ClearClipboard(void) Clears the clipboard and frees the memory allocated for it. Called by D-Flat when message processing terminates. ------------------------------------------------------------------- WINDOW WatchIcon(void) Displays a wristwatch icon on the screen. The icon has control of the keyboard and mouse. You must send the CLOSE_WINDOW message to the WINDOW handle that WatchIcon returns to get rid of the icon. Use this icon to tell the user to please stand by during long processes. Call handshake frequently during these processes to update the date display in the status bar and to allow the watch icon to move when the user moves the mouse. ------------------------------------------------------------------- Configurable Items Global Symbol File Value Description ------------- --------- ----- --------------------------------------- MAXMESSAGES DFLAT.H 50 Maximum D-Flat messages queued MAXCONTROLS DIALBOX.H 26 Maximum Controls on a dialog box MAXRADIOS DIALBOX.H 20 Maximum radio buttons in a group MAXSAVES SYSTEM.H 50 Maximum cursor saves MAXPULLDOWNS MENU.H 15 Maximum number of pull-down menus on a menu bar (including cascading menus) MAXSELECTIONS MENU.H 15 Maximum number of selections on a pull-down menu (includes separators) MAXCASCADES MENU.H 3 Maximum nesting level of cascaded menus MAXTEXTLEN DFLAT.H 65000 Maximum text buffer EDITLEN DFLAT.H 1024 Starting length for multiline EDITBOX ENTRYLEN DFLAT.H 256 Starting length for single-line EDITBOX GROWLENGTH DFLAT.H 64 EDITBOX buffers grow by this much