classes. Most of the
functionality of those classes is implemented and documented in this
section.
External menus (those defined in resources) would be created and used
via the ExternalMenu
class. Internal menus (those defined at runtime
by the application code) would be created and used via the
InternalMenu
and PopupMenu
classes. Since both of these
classes are subclasses of the Menu
class, they inherit most of
their functionality from it.
r = mAssociate(menu, id, fun); object menu; /* a menu object */ int id; /* menu item id */ long (*fun)(object); /* function to execute */ object r; /* the menu object */ |
This method is used to associate a function with a menu item such that if
the user selects the menu item, fun
gets executed.
In the case of external menus, id
is normally a macro created by
the resource editor while the programmer defines the menu and identifies
a particular menu option.
fun
is the application specific function which automatically gets
executed whenever the user selects the indicated option. fun
has
the following structure:
static long menu_option(object wind) { . . . return 0L; } |
Where wind
is the window object which the menu is attached to.
The value returned is what is returned by the window procedure associated
with the window. This value is normally 0 and is fully documented by
the Windows documentation under the WM_COMMAND
message.
The value returned is the menu object passed.
Example: object myMenu; mAssociate(myMenu, ID_FILE_OPEN, menu_option); |
See also: AddMenuOption::InternalMenu, AddMenuOption::PopupMenu
r = gDeepDispose(menu); object menu; /* a menu object */ object r; /* NULL */ |
This method is used to dispose of a menu object and all menu objects
which were pushed (via Push
) into the same menu stack. It is not
often needed because menus associated with a window are automatically
disposed of (via this method) when the window is disposed.
If menu
is an internal menu, all associated popup menus will
also be disposed.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object myMenu; myMenu = gDeepDispose(myMenu); |
See also: Dispose, Push
r = gDispose(menu); object menu; /* a menu object */ object r; /* NULL */ |
This method is used to dispose of a menu object when it is no longer
needed. It is not often needed because menus associated with a window
are automatically disposed of (via DeepDispose
) when the window
is disposed.
If menu
is an internal menu, all associated popup menus will
also be disposed.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object myMenu; myMenu = gDispose(myMenu); |
See also: DeepDispose
h = gHandle(menu); object menu; /* menu object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with a menu object.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object myMenu; HANDLE h; h = gHandle(myMenu); |
fun = mMenuFunction(menu, id); object menu; /* a menu object */ int id; /* menu item id */ long (*fun)(object); /* function to execute */ |
This method is used to obtain the function which was associated with a
menu item.
See also: Associate
prev = gPop(top); object top; /* top menu */ object prev; /* previous menu */ |
This method is used to dispose of menu top
and gain access to the
next menu in menu top
’s last in, first out list. It is mainly
used by the Window
class in order to support the ability to
change a menu and later return to a previous menu. The value returned
is the next menu in the stack.
Example: object myMenu, subMenu; HANDLE h; subMenu = gPop(myMenu); |
See also: Push, Use::Window, PopMenu::Window
r = gPush(top, psh); object top; /* top menu */ object psh; /* pushed menu */ object r; /* top menu */ |
This method is used to push menu (psh
) into a last in, first out
stack accessible through menu top
. It is mainly used by the
Window
class in order to support the ability to change a menu and
later return to a previous menu. The value returned is the top menu
passed.
Example: object myMenu, subMenu; HANDLE h; h = gPush(myMenu, subMenu); |
See also: Pop, Use::Window, PopMenu::Window
r = mSetMode(menu, id, mode); object menu; /* menu */ unsigned id; /* menu item */ unsigned mode; /* item mode */ object r; /* menu */ |
This method is used to set the mode associated with a menu item. This mode specifies whether the menu is enabled, disabled or grayed.
In the case of external menus, id
is normally a macro created by
the resource editor while the programmer defines the menu and identifies
a particular menu option. In the case of internal menu’s, id
is the number returned by AddMenuOption::InternalMenu
or
AddMenuOption::PopupMenu
.
mode
is a Windows defined macro and may be one of the following:
MF_ENABLED to enable the menu item MF_DISABLED to disable the menu item MF_GRAYED to gray the menu option |
The value returned is the menu passed.
Example: object myMenu; mSetMode(myMenu, ID_FILE_OPEN, MF_DISABLED); |
See also: AddMenuOption::InternalMenu, AddMenuOption::PopupMenu
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ExternalMenu
class is used to access menus which were defined
using the resource editor. Since this class is a subclass of Menu
,
all of Menu
’s functionality is accessible through instance of this
class. Therefore, see the Menu
class for additional functionality.
menu = mLoad(ExternalMenu, id); unsigned id; /* menu id */ object menu; /* menu */ |
This method is used to create a new menu object representing a menu defined with the resource editor.
id
is normally a macro created by the resource editor which identifies
a particular menu.
The value returned is a new object representing the menu or NULL
if
the menu identified is not found.
Example: object myMenu; myMenu = mLoad(ExternalMenu, MY_MENU); |
See also: LoadStr, LoadMenu::Window, LoadMenuStr::Window
menu = gLoadStr(ExternalMenu, id); char *id; /* menu id */ object menu; /* menu */ |
This method is used to create a new menu object representing a menu defined with the resource editor.
id
is a string which names the desired menu. This name is
defined by the resource editor and identifies a particular menu.
The value returned is a new object representing the menu or NULL
if
the menu identified is not found.
Example: object myMenu; myMenu = gLoadStr(ExternalMenu, "mymenu"); |
See also: Load, LoadMenu::Window, LoadMenuStr::Window
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The InternalMenu
class is used to enable an application to create
menus on the fly – without the need to pre-specify the menu’s structure
with the resource editor. Since this class is a subclass of
Menu
, all of Menu
’s functionality is accessible through
instance of this class. Therefore, see the Menu
class for
additional functionality.
id = gAddMenuOption(mnu, ttl, fun) object menu; /* menu */ char *ttl; /* title */ long (*fun)(); /* function */ int id; /* item id */ |
This method is used to append a new option to internal menu object
mnu
and associate it to an application specific function
(fun
). Once this is done, if the user selects the new menu
option the function fun
will be executed.
ttl
represents the character string which will be displayed
in the menu. ttl
may also contain an embedded ampersand (&)
character. This causes the character following the ampersand to
be underlined. It also causes the following character to be the
Alt key selection the user can use to quickly select a menu option.
fun
is the function which will be executed when the user selects
the menu option and has the following form:
long fun(object wind) { . . . return 0L; } |
The function executed (fun
) is passed the window object and
returns a long. The return value is documented in the Windows documentation
under the message named WM_COMMAND
. It should normally be 0L
.
This method returns a unique WDS generated id which identifies this particular menu option and may be used to control the status of the option.
Example: static long file_message(object wind) { gMessage(wind, "File_Message"); return 0L; } . . mnu = vNew(InternalMenu); gAddMenuOption(mnu, "&File", file_message); |
See also: AddPopupMenu
id = gAddPopupMenu(mnu, ttl, pm) object mnu; /* menu */ char *ttl; /* title */ object pm; /* Popup menu */ object r; /* menu */ |
This method is used to append a new option to menu object mnu
and
associate it to a popup menu. Once this is done, if the user selects
the new menu option the popup menu will be displayed.
ttl
represents the character string which will be displayed
in the menu. ttl
may also contain an embedded ampersand (&)
character. This causes the character following the ampersand to
be underlined. It also causes the following character to be the
Alt key selection the user can use to quickly select a menu option.
pm
is a popup menu object created with the PopupMenu
class.
This method returns mnu
.
Example: object mnu, pm; mnu = vNew(InternalMenu); pm = vNew(PopupMenu, mnu); gAddPopupMenu(mnu, "&File", pm); |
See also: AddMenuOption, New::PopupMenu
menu = vNew(InternalMenu); object menu; /* menu */ |
This method is used to create a new internal menu. An internal menu is one which is not pre-specified with the resource editor. It may therefore be structured at runtime.
The object returned is a new internal menu object with no items associated with it.
Example: object myMenu; myMenu = vNew(InternalMenu); |
See also: AddMenuOption, AddMenu, Use::Window, LoadMenu::Window
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The PopupMenu
class is used in conjunction with the
InternalMenu
class in order to provide a nested menu structure.
Nesting of popup menus is supported to arbitrary levels.
id = gAddMenuOption(mnu, ttl, fun) object menu; /* menu */ char *ttl; /* title */ long (*fun)(); /* function */ int id; /* item id */ |
This method works exactly like AddMenuOption::InternalMenu
.
See that description for full documentation.
See also: AddPopupMenu, AddSeparator
id = gAddPopupMenu(mnu, ttl, pm) object mnu; /* menu */ char *ttl; /* title */ object pm; /* Popup menu */ object r; /* menu */ |
mnu
is the popup menu which is to act as the parent of pm
and may be arbitrarily nested.
This method is the same as AddPopupMenu::InternalMenu
. See that
method for complete documentation.
See also: AddMenuOption, AddSeparator
r = gAddSeparator(mnu) object mnu; /* menu */ object r; /* menu */ |
This method is used to append a horizontal bar to the end of a popup menu. Any menu items added subsequently will appear after the horizontal separator.
The menu object passed is returned.
Example: gAddSeparator(pm); |
See also: AddMenuOption
r = gDispose(menu); object menu; /* a menu object */ object r; /* NULL */ |
This method is used to dispose of a menu object when it is no longer
needed. It is not often needed because popup menus associated with
other menus are automatically disposed of (via DeepDispose
) when
the top level menu is disposed.
This class also provides a DeepDispose
which performs the same
function.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object myMenu; myMenu = gDispose(myMenu); |
See also: DeepDispose::Menu
h = gHandle(menu); object menu; /* menu object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with a popup menu object.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object myMenu; HANDLE h; h = gHandle(myMenu); |
fun = mMenuFunction(menu, id); object menu; /* a menu object */ int id; /* menu item id */ long (*fun)(object); /* function to execute */ |
This method is used to obtain the function which was associated with a
menu item.
See also: AddMenuOption
pm = vNew(PopupMenu, tm); object tm; /* top menu */ object pm; /* popup menu */ |
This method is used to create a new popup menu. A popup menu is one which pops up or appears when a user selects an associated menu option. Popup menus are used in conjunction with internal menus in order to create arbitrarily complex menu structures.
tm
is the top menu object. It must be an InternalMenu
,
regardless of where the new popup menu will be nested.
The object returned represents the new popup menu created and may be used to add items to that menu.
Example: object myMenu, pm; myMenu = vNew(InternalMenu); pm = vNew(PopupMenu, myMenu); gAddPopupMenu(myMenu, "&File", pm); |
See also: AddMenuOption, AddPopupMenu, AddSeparator,
AddPopupMenu::InternalMenu
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Dialog
class implements all the functionality which is common
to the ModalDialog
and ModelessDialog
classes, and although
this class is not used directly, most of their functionality is documented
in this section.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since all dialog instance methods have the dialog object as the first
argument (referred to as dlg
), this argument will not be described
each time. It always refers to the dialog object which you wish to
perform the desired operation on.
Many of the methods associated with this class take an argument
identified as id
. This is a macro defined by the programmer via
the resource editor when the dialog is being defined and is used to
uniquely identify a particular control within the dialog. Due to the
fact that this argument has the same meaning for every method which
uses it, it will not be defined each time.
The variable ctl
will always refer to a control object. Each
control object represents a unique control within a dialog. Each
control object will be an instance of one of the subclasses of the
Control
class (such as TextControl
or
NumericControl
).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ctl = mAddControl(dlg, ctlClass, id); object dlg; /* a dialog object */ object ctlClass; /* class of control */ unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object and associate it to
a control defined in the dialog. ctlClass
must be literally
one of the subclasses of the Control
class (such as
TextControl
, CheckBox
, RadioButton
, etc).
See the class hierarchy for a complete list.
id
identifies which control within dialog dlg
to associate
the new control object with.
The value returned (ctl
) is the new control object created and
will be an instance of the class indicated by the ctlClass
argument. This object can be configured and queried via the protocol
defined by its class. See that section for available options. Setting
various options associated with this object will control default values
associated with the control and how this control functions within the
dialog.
Example: object dlg, ctl; ctl = mAddControl(dlg, TextControl, PERSONS_NAME); |
See also: GetControl
r = gAddDlgHandlerAfter(dlg, msg, func); object dlg; /* a dialog object */ unsigned msg; /* message */ BOOL (*func)(); /* function pointer */ object r; /* the dialog obj */ |
This method is used to associate function func
with Windows dialog
message msg
for dialog dlg
. Whenever dialog dlg
receives message msg
, func
will be called.
dlg
is the dialog object who’s messages you wish to process.
msg
is the particular message you wish to trap. These messages
are fully documented in the Windows documentation in the Messages
section. They normally begin with WM_
.
func
is the function which gets called whenever the specified
message gets received and takes the following form:
BOOL func(object dlg, HWND hdlg, UINT mMsg, WPARAM wParam, LPARAM lParam) { . . . return FALSE; /* or whatever is appropriate */ } |
Where dlg
is the dialog being sent the message. The remaining
arguments and return value is fully documented in the Windows documentation
under the DialogProc
function and the Windows Messages documentation.
WDS keeps a list of functions associated with each message associated
with each dialog. When a particular message is received the appropriate
list of handler functions gets executed sequentially.
AddDlgHandlerAfter
appends the new function to the end of this list,
and AddDlgHandlerBefore
adds the new function to the beginning of
the list.
Windows will only see the return value of the last message handler executed.
Example: int hSize, vSize; static BOOL process_wm_size(object dlg, HWND hwnd, UINT mMsg, WPARAM wParam, LPARAM lParam) { hSize = LOWORD(lParam); vSize = HIWORD(lParam); return 0L; } . . gAddDlgHandlerAfter(dlg, (unsigned) WM_SIZE, process_wm_size); . . |
See also: AddDlgHandlerBefore
r = gAddDlgHandlerBefore(dlg, msg, func); object dlg; /* a dialog object */ unsigned msg; /* message */ BOOL (*func)(); /* function pointer */ object r; /* the dialog obj */ |
This function is fully documented under AddDlgHandlerAfter
.
See also: AddDlgHandlerAfter
pflg = gAutoDispose(dlg, flg); object dlg; /* a dialog object */ int flg; /* desired mode */ int pflg; /* previous mode set */ |
This method is used to control the auto disposal facility associated with a given dialog. The default is disabled for modal dialogs and enabled for modeless dialogs.
If enabled, the auto dispose feature will cause the dialog object
(dlg
) to be automatically disposed of whenever the user accepts
or aborts the dialog. If disabled, the application may continue to use
the object (for querying control values for example) after the dialog
has been terminated. If the auto dispose feature is disabled the
application must explicitly dispose of the object when it is no longer
needed.
Note that if the auto dispose feature is used, the gCompletionFunction
method may be used to access the control values immediately prior to
the object’s automatic disposal.
Set flg
to 1 to enable the feature and 0 to disable it. The
previous state will be returned.
Example: object dlg; gAutoDispose(dlg, 1); |
See also: CompletionFunction, Perform, SetResult
r = gBackBrush(dlg, brsh); object dlg; /* a dialog object */ object brsh; /* brush object */ object r; /* dlg */ |
This method is used to set the brush object which is used for the background of the dialog. Any previously associated brush object will be disposed. This brush object will also be automatically disposed when the dialog is disposed.
The dialog passed is returned.
Example: object dlg; gBackBrush(dlg, vNew(SolidBrush, 0, 255, 0)); |
See also: TextBrush, SetBackBrush::Application
and the Brush
classes
r = gCompletionFunction(dlg, fun); object dlg; /* dialog object */ int (*fun)(); /* completion function */ object r; /* dialog object */ |
This method is used to associated a C function with a dialog such that
when the user accepts or aborts the dialog, function fun
will
get executed by WDS. The function will get executed prior to any automatic
disposal of the dialog object.
The completion function facility is best used in conjunction with modeless dialogs and the auto dispose facility in order to process control values when the user accepts the dialog and prior to the automatic disposal of the dialog object.
The format of fun
is as follows:
r = fun(dlg, res); object dlg; /* the dialog object */ int res; /* result status of the dialog */ int r; /* result for gPerform */ |
Where res
will be TRUE
if the user accepted the dialog or
FALSE
if the user canceled the dialog. r
is the value
which will become the result of the dialog which is returned by gPerform
(if it was a modal dialog). r
will normally be res
.
Example: static int fun(object dlg, int res) { . . return res; } gCompletionFunction(dlg, fun); |
See also: AutoDispose, Perform, SetTag, SetResult
val = mCtlDoubleValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ double val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a C double. For example, if the control was a numeric control and the user entered “3.141”, then this method would return a double “3.141”.
Example: object dlg; double val; val = mCtlDoubleValue(dlg, PI_VALUE); |
See also: CtlStringValue, CtlShortValue, ...
CtlValue
val = mCtlLongValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ long val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a C long. For example, if the control was a numeric control and the user entered “6”, then this method would return a long “6”.
In the case of date controls, the value returned will be in the form YYYYMMDD. For example November 24, 1956 would be 19561124.
Example: object dlg; long val; val = mCtlLongValue(dlg, PERSONS_AGE); |
See also: CtlStringValue, CtlShortValue, ...
CtlValue
val = mCtlShortValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ short val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a C short. For example, if the control was a numeric control and the user entered “6”, then this method would return a short “6”.
In the case of a list box or combo box the value returned will be in terms of an ordinal value. This value returned is a zero based index from top to bottom indicating the selection made by the user. If no selection was made negative value will be returned.
In the case of check boxes and radio buttons this method will return 0 if the button is not selected, 1 if the button is selected, and 2 if the button is grayed.
In the case of scroll bars, this method will return a short value between the minimum and maximum set for the control which indicates where the control was set to.
mCtlLongValue
should be used for date controls.
Example: object dlg; short val; val = mCtlShortValue(dlg, PERSONS_AGE); |
See also: CtlStringValue, CtlLongValue, ...
CtlValue
val = mCtlStringValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ char *val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a C character string. For example, if the control was a text control and the user entered “Miami”, then this method would return a pointer to the C string “Miami”.
If the control being accessed is a list box or combo box, the value
returned will be a string representation of the text associated with the
choice made by the user. See CtlShortValue
or IndexValue
to get an ordinal value for this control type.
The character pointer returned will not be valid once the dialog or control has been disposed. Therefore, the value should be kept by some other means if it is desired past the life of the dialog.
Example: object dlg; char *val; val = mCtlStringValue(dlg, PERSONS_NAME); |
See also: CtlShortValue, CtlLongValue, ...
CtlValue
val = mCtlUnsignedShortValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ unsigned short val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a C unsigned short. For example, if the control was a numeric control and the user entered “6”, then this method would return a unsigned short “6”.
mCtlLongValue
should be used for date controls.
Example: object dlg; unsigned short val; val = mCtlUnsignedShortValue(dlg, PERSONS_AGE); |
See also: CtlStringValue, CtlLongValue, ...
CtlValue
val = mCtlValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ object val; /* control value */ |
This method is used to gain access to the value associated with a particular control as a Dynace object. For example, if the control was a text control and user entered “Miami”, then this method would return a Dynace string object (not a normal C string) which represents the value typed in. This returned value may be used and accessed like any other Dynace object using the appropriate interface mechanism.
If the control being accessed is a list box or combo box, the value
returned will be a representation of the text associated with the choice
made by the user. See IndexValue
or CtlShortValue
to get
a numeric representation for this control type.
The object returned will be automatically disposed when the dialog is
disposed, therefore, a copy (via gCopy
) should be made of it if
its existence is required subsequent to the dialog’s disposal.
WDS also provides several methods to obtain normal C data types directly.
Example: object dlg, val; val = mCtlValue(dlg, PERSONS_NAME); |
See also: CtlStringValue, CtlShortValue, CtlLongValue, ...
This method performs the same function as Dispose
. See that
method for details.
r = gDispose(dlg); object dlg; /* a dialog object */ object r; /* NULL */ |
This method is used to remove and dispose of a dialog object when it is no longer needed. This method should be called on all dialogs when they are no longer needed. In addition to disposing of the dialog, this method will also dispose of all the control objects associated with the dialog.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object dlg; dlg = gDispose(dlg); |
See also: AutoDispose
brsh = gGetBackBrush(dlg); object dlg; /* dialog object */ object brsh; /* brush object */ |
This method is used to obtain the background brush object which has been associated with the dialog. If no specific background brush was associated with the dialog this method will return the application default background brush, which is what the dialog uses when no specific brush is specified.
Example: object dlg, brsh; brsh = gGetBackBrush(dlg); |
See also: BackBrush, GetTextBrush, GetBackBrush::Application
ctl = mGetControl(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to gain access to a control object which has been previously associated with a particular control via its associated control id. The control object is returned.
Example: object dlg, ctl; ctl = mGetControl(dlg, PERSONS_NAME); |
See also: AddControl
prnt = gGetParent(dlg); object dlg; /* dialog object */ object prnt; /* parent window object */ |
This method is used to obtain the parent window object associated
with dialog dlg
. This parent window would have established
when the dialog object was created.
Example: object dlg, parentWind; parentWind = gGetParent(dlg); |
See also: NewDialog::ModalDialog, NewDialog::ModelessDialog
r = gGetTag(dlg); object dlg; /* dialog object */ object r; /* tag */ |
This method is used to obtain a Dynace object which has been associated
with a dialog via SetTag
. The value return is the object which has
been associated with the dialog object dlg
. If there is no object
associated with the dialog, NULL
will be returned.
Example: object dlg, someObj; someObj = gGetTag(dlg); |
See also: SetTag, SetTag::Window
brsh = gGetTextBrush(dlg); object dlg; /* dialog object */ object brsh; /* brush object */ |
This method is used to obtain the text brush object which has been associated with the dialog. If no specific text brush was associated with the dialog this method will return the application default text brush, which is what the dialog uses when no specific brush is specified.
Example: object dlg, brsh; brsh = gGetTextBrush(dlg); |
See also: TextBrush, GetBackBrush, GetTextBrush::Application
h = gHandle(dlg); object dlg; /* dialog object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with
a dialog object. It will only return a valid handle while the dialog
is being performed via gPerform
. NULL
will be returned
otherwise.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object dlg; HANDLE h; h = gHandle(dlg); |
val = mIndexValue(dlg, id); object dlg; /* a dialog object */ unsigned id; /* control id */ object val; /* control value */ |
This method is used to gain access to a Dynace object (as opposed to a normal C integer) representing the value associated with a list box or combo box in terms of an ordinal value. This value returned is a zero based index from top to bottom indicating the selection made by the user. If no selection was made the object will represent a negative value. This returned value may be used and accessed like any other Dynace object using the appropriate interface mechanisms.
The object returned will be automatically disposed when the dialog is
disposed, therefore, a copy (via gCopy
) should be made of it if
its existence is required subsequent to the dialog’s disposal.
WDS also provides several methods to obtain normal C data types directly.
Example: object dlg, val; val = mIndexValue(dlg, SOME_LISTBOX); |
See also: CtlShortValue, CtlValue
flg = gInDialog(dlg); object dlg; /* a dialog object */ int flg; /* in dialog flag */ |
This method is used to determine whether a given dialog is currently
being “performed” via gPerform
. Prior and subsequent to
performing a dialog this method will return 0. A 1 will be returned
if the dialog is currently being performed.
Example: object dlg; int flg; flg = gInDialog(dlg); |
See also: Perform
r = gMessage(dlg, msg); object dlg; /* dialog object */ char *msg; /* message */ object r; /* dialog object */ |
This method is used to open up a temporary informational window. The
window will contain the message given by msg
and the user must
acknowledge the window prior to continuing by hitting an OK button.
This method may only be used either while the dialog is being performed or at any time if it has an associated parent window.
The value returned is the dialog passed.
Example: object dlg; gMessage(dlg, "Press OK to continue."); |
See also: MessageWithTopic
r = gMessageWithTopic(dlg, msg, tpc); object dlg; /* dialog object */ char *msg; /* message */ char *tpc; /* help topic */ object r; /* dialog object */ |
This method is used to open up a temporary informational dialog. The
dialog will contain the message given by msg
and the user must
acknowledge the dialog prior to continuing by hitting an OK button.
If the user hits the F1
key while presented with the message,
the help topic identified by tpc
will get displayed via the Windows
help system.
This method may only be used either while the dialog is being performed or at any time if it has an associated parent window.
The value returned is the dialog passed.
Example: object dlg; gMessageWithTopic(dlg, "Press OK to continue.", "mytopic"); |
See also: Message
and the HelpSystem
class.
r = gPerform(dlg); object dlg; /* a dialog object */ int r; /* result */ |
Once a dialog is created and fully specified, this method is used to
actually display the dialog and allow the user to interact with it.
The dialog will remain active until the user pushes the push buttons
with the label IDOK
or IDCANCEL
.
What occurs after calling gPerform
depends on whether the dialog
was a modal or modeless dialog.
Control initial values should be set prior to calling gPerform
.
MODAL DIALOGS
If the dialog being performed is a modal, then once gPerform
is
evoked the user will be able to interact with the dialog and gPerform
will not return until the user either accepts or aborts the entire dialog.
This, in effect, will prevent the user from switching to any other window
or dialog within the application until the dialog is completed.
Finally, the value returned by gPerform
will be the Windows
constant FALSE
if the user canceled the dialog, the Windows
constant TRUE
if the user accepted the dialog, or the
value returned by any completion function which was attached to the
dialog (via CompletionFunction
).
Once gPerform
returns, the dialog object may be queried in
order to obtain the final values associated with each control.
Unless the auto dispose feature is manually set for a modal dialog, the dialog object is not automatically disposed and must be when no longer needed.
MODELESS DIALOGS
Modeless dialogs operate different from modal dialogs. When
gPerform
is evoked on a modeless dialog, gPerform
returns
immediately with a 0 value. At that point the user is presented with the
dialog and allowed to edit it. During that time your program would typically
return to the menu and wait for further user selections. The user may
continue with the current dialog, abort it, or switch to another window
within the application with the ability to return at any point. All the
user interaction is automatically handled by Windows and WDS.
Since the application code has gone on about its business after a call
to gPerform
two things are left to be completed whenever the user
finally accepts or aborts the dialog. First, the application will
typically want to do something with the data the user has entered on the
dialog. And second, the dialog object will need to be disposed when
it’s no longer needed.
When using modeless dialogs the programmer normally attaches a completion
function to the dialog via gCompletionFunction
. What this does
is cause the completion function to be executed whenever the user
accepts or aborts the dialog. This application specific function can be
used to perform the final processing of the dialog’s data. See
gCompletionFunction
for complete details.
By default, the auto dispose flag associated with modeless dialogs is
normally enabled. This causes WDS to automatically dispose of a dialog
object and all associated controls immediately subsequent to executing
the completion function. This way everything is cleaned up automatically.
This feature may be disabled via gAutoDispose
, in which case the
application must be sure to dispose of the unneeded object.
Example: object dlg; int r; r = gPerform(dlg); |
See also: CompletionFunction, AutoDispose
r = gSetResult(dlg, obj); object dlg; /* a dialog object */ object obj; /* result object */ object r; /* dlg */ |
This method is used to associated a Dynace short integer object with a dialog such that when the dialog is completed or canceled by the user, the associated object will be set to the dialog’s result value. This feature is most often needed in conjunction with modeless dialogs and the auto dispose feature. It can be used to find out what happened to a dialog subsequent to the dialog object being disposed.
The object associated with the dialog will never be disposed by WDS and must be manually disposed when it is no longer needed.
Example: object dlg, obj; gSetResult(dlg, obj = gNewWithInt(ShortInteger, -1)); |
See also: AutoDispose, Perform, SetTag
r = gSetTag(dlg, tag); object dlg; /* a dialog object */ object tag; /* tag */ object r; /* previous tag */ |
This method is used to associated an arbitrary Dynace object with a
dialog object. This may later be retrieved via the GetTag
method.
Since WDS passes around the dialog object to all Dialog
methods
this mechanism may be used to pass additional information with the
dialog. And since Dynace treats all objects in a uniform manner, this
information attached to the dialog may be arbitrarily complex.
WDS does not dispose of the tag when the dialog object is disposed.
This method returns any previous object associated with the dialog or
NULL
.
Example: object dlg; gSetTag(dlg, gNewWithInt(ShortInteger, 17)); |
See also: GetTag, SetTag::Window
pt = gSetTopic(dlg, tpc); object dlg; /* dialog object */ char *tpc; /* help topic */ char *pt; /* previous help topic */ |
This method is used to associate help text with dialog dlg
.
The help text is defined using the Windows help system and labeled
with the topic indicated by tpc
. Then, if the user hits
the F1 key while in the dialog, WDS will automatically bring up
the Windows help system and find the indicated topic.
WDS also supports window and control specific topics. See the appropriate sections.
This method returns any previous topic associated with the dialog.
Example: object dlg; gSetTopic(dlg, "myDialogHelp"); |
See also: The HelpSystem
class and SetTopic::Control
r = gTextBrush(dlg, brsh); object dlg; /* a dialog object */ object brsh; /* brush object */ object r; /* dlg */ |
This method is used to set the brush object which is used for foreground text which is displayed. Any previously associated brush object will be disposed. This brush object will also be automatically disposed when the dialog is disposed.
The dialog passed is returned.
Example: object dlg; gTextBrush(dlg, vNew(SolidBrush, 255, 0, 0)); |
See also: BackBrush, SetTextBrush::Application
and the Brush
classes
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Modal dialogs are created with the methods described in this section.
However, since the ModalDialog
class is a subclass of Dialog
,
and the Dialog
class implements all the functionality common to
both the ModalDialog
and ModelessDialog
classes, the
majority of the functionality is inherited from and documented in
the Dialog
class. Therefore, see the Dialog
class
for documentation on additional functionality available to this class.
dlg = mNewDialog(ModalDialog, id, wnd); unsigned id; /* dialog id */ object wnd; /* parent window */ object dlg; /* dialog object */ |
This method is used to create a new modal dialog. The dialog must have
been previously laid out using the resource editor. The id
is a macro generated by the resource editor while the programmer defines
the dialog. This id uniquely identifies a particular dialog.
wnd
allows the specification of the parent window object associated
with the new dialog. This is an optional parameter and may be NULL
if it not desired. If you do specify a parent window, the dialog will
iconize when the window is iconized and will be disposed if the window
is disposed.
The object returned represents the new dialog created and may be used to further control the dialog.
Example: object wind, dlg; dlg = mNewDialog(ModalDialog, MY_DIALOG, wind); |
See also: NewDialogStr, Perform::Dialog, NewDialog::ModelessDialog
dlg = gNewDialogStr(ModalDialog, id, wnd); char *id; /* dialog id */ object wnd; /* parent window */ object dlg; /* dialog object */ |
This method is used to create a new modal dialog. The dialog must have
been previously laid out using the resource editor. The id
is
the string name associated with the dialog. This id uniquely identifies
a particular dialog.
wnd
allows the specification of the parent window object associated
with the new dialog. This is an optional parameter and may be NULL
if it not desired. If you do specify a parent window, the dialog will
iconize when the window is iconized and will be disposed if the window
is disposed.
The object returned represents the new dialog created and may be used to further control the dialog.
Example: object wind, dlg; dlg = gNewDialogStr(ModalDialog, "mydialog", wind); |
See also: NewDialog, Perform::Dialog, NewDialogStr::ModelessDialog
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Modeless dialogs are created with the methods described in this section.
However, since the ModelessDialog
class is a subclass of
Dialog
, and the Dialog
class implements all the
functionality common to both the ModalDialog
and
ModelessDialog
classes, the majority of the functionality is
inherited from and documented in the Dialog
class. Therefore,
see the Dialog
class for documentation on additional
functionality available to this class.
dlg = mNewDialog(ModelessDialog, id, wnd); unsigned id; /* dialog id */ object wnd; /* parent window */ object dlg; /* dialog object */ |
This method is used to create a new modeless dialog. The dialog must have
been previously laid out using the resource editor. The id
is a macro generated by the resource editor while the programmer defines
the dialog. This id uniquely identifies a particular dialog.
wnd
allows the specification of the parent window object associated
with the new dialog. This is an optional parameter and may be NULL
if it not desired. If you do specify a parent window, the dialog will
iconize when the window is iconized and will be disposed if the window
is disposed.
When a new modeless dialog is created, its auto dispose mode is enabled. This means that, unless disabled, the object representing the dialog will be automatically disposed when the user closes the window. This is done due to the independent nature of modeless dialogs and the need to be sure that object no longer needed are disposed. Note that the programmer may specify a function which gets executed prior to the disposal of a modeless dialog in order to capture any data.
The object returned represents the new dialog created and may be used to further control the dialog.
Example: object wind, dlg; dlg = mNewDialog(ModelessDialog, MY_DIALOG, wind); |
See also: NewDialogStr, Perform::Dialog, NewDialog::ModalDialog,
CompletionFunction::Dialog, AutoDispose::Dialog
dlg = gNewDialogStr(ModlessDialog, id, wnd); char *id; /* dialog id */ object wnd; /* parent window */ object dlg; /* dialog object */ |
This method is used to create a new modeless dialog. The dialog must have
been previously laid out using the resource editor. The id
is
the string name associated with the dialog. This id uniquely identifies
a particular dialog.
wnd
allows the specification of the parent window object associated
with the new dialog. This is an optional parameter and may be NULL
if it not desired. If you do specify a parent window, the dialog will
iconize when the window is iconized and will be disposed if the window
is disposed.
When a new modeless dialog is created, its auto dispose mode is enabled. This means that, unless disabled, the object representing the dialog will be automatically disposed when the user closes the window. This is done due to the independent nature of modeless dialogs and the need to be sure that object no longer needed are disposed. Note that the programmer may specify a function which gets executed prior to the disposal of a modeless dialog in order to capture any data.
The object returned represents the new dialog created and may be used to further control the dialog.
Example: object wind, dlg; dlg = gNewDialogStr(ModelessDialog, "mydialog", wind); |
See also: NewDialog, Perform::Dialog, NewDialogStr::ModalDialog,
CompletionFunction::Dialog, AutoDispose::Dialog
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Control
class is never used directly. It is used to group
functionality common to all the control types which are all subclasses
of this class. Therefore, this section documents all the methods which
are accessible to all subclasses of this class.
Control instances are normally created via AddControl::Dialog
and may be subsequently accessed via GetControl::Dialog
.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since all control instance methods have the control object as their
first argument (referred to as ctl
), this argument will not be
described each time. It always refers to the control object which you
wish to perform the desired operation on. Each control object will be
an instance of one of the subclasses of the Control
class (such
as TextControl
or NumericControl
).
Many of the methods associated with this class take an argument
identified as id
. This is a macro defined by the programmer via
the resource editor when the dialog is being defined and is used to
uniquely identify a particular control within the dialog. Due to the
fact that this argument has the same meaning for every method which
uses it, it will not be defined each time.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
r = gAddHandlerAfter(ctl, msg, func); object ctl; /* a control object */ unsigned msg; /* message */ long (*func)(); /* function pointer */ object r; /* the control obj */ |
This method is used to associate function func
with Windows control
message msg
for control ctl
. Whenever control ctl
receives message msg
, func
will be called.
ctl
is the control object who’s messages you wish to process.
msg
is the particular message you wish to trap. These messages
are fully documented in the Windows documentation in the Messages
section. They normally begin with WM_
.
func
is the function which gets called whenever the specified
message gets received and takes the following form:
long func(object ctl, HWND hwnd, UINT mMsg, WPARAM wParam, LPARAM lParam) { . . . return 0L; /* or whatever is appropriate */ } |
Where ctl
is the control being sent the message. The remaining
arguments and return value is fully documented in the Windows documentation
under the WindowProc
function and the Windows Messages documentation.
WDS keeps a list of functions associated with each message associated
with each control. When a particular message is received the appropriate
list of handler functions gets executed sequentially.
AddHandlerAfter
appends the new function to the end of this list,
and AddHandlerBefore
adds the new function to the beginning of
the list.
WDS may also, and optionally, execute the Windows default procedure
associated with a given message either before or after the user added
list of functions. This behavior may be controlled via
DefaultProcessingMode
.
Windows will only see the return value of the last message handler executed including, if applicable, the default.
Example: int hSize, vSize; static long process_wm_size(object ctl, HWND hwnd, UINT mMsg, WPARAM wParam, LPARAM lParam) { hSize = LOWORD(lParam); vSize = HIWORD(lParam); return 0L; } . . gAddHandlerAfter(ctl, (unsigned) WM_SIZE, process_wm_size); . . |
See also: DefaultProcessingMode, AddHandlerBefore, CallDefaultProc
r = gAddHandlerBefore(ctl, msg, func); object ctl; /* a control object */ unsigned msg; /* message */ long (*func)(); /* function pointer */ object r; /* the control obj */ |
This function is fully documented under AddHandlerAfter
.
See also: AddHandlerAfter
r = gCallDefaultProc(ctl, msg, wp, lp) object ctl; /* a control object */ unsigned msg; /* message */ WPARAM wp; /* wParam value */ LPARAM lp; /* lParam value */ long r; /* result of call */ |
This method is used to explicitly call the default Windows message handler
associated with message msg
. This method is normally called from
within a programmer defined message handler (see AddHandlerAfter
)
which is provided with the wp
and lp
parameters. These
parameters are fully documented in the Windows Messages documentation
and relate directly to the particular message.
msg
is the particular message you wish to affect. These messages
are fully documented in the Windows documentation in the Messages
section. They normally begin with WM_
.
Example: gCallDefaultProc(ctl, msg, wParam, lParam); |
See also: DefaultProcessingMode, AddHandlerAfter
r = gCheckFunction(ctl, fun); object ctl; /* control object */ int (*fun)(); /* check function */ object r; /* ctl object */ |
This method is used to associate an auxiliary checking function to a control. When a dialog is accepted, WDS goes through each control to assure the validity of the data associated with each control as defined by the control object. The ability to associated an additional function for validating the data associated with a control gives the programmer the ability to perform any additional application specific checking against a control’s data.
The auxiliary checking function takes the following form:
int fun(object ctl, object val, char *buf) { .... } |
Where ctl
is the control object, and val
is a Dynace object which
represents the value the control has associated with it. buf
is a
pointer to a buffer area which fun
must set to an appropriate error
message if an error occurs. fun
returns a 1 if an error occurs and
0 otherwise.
All controls support this feature except the PushButton
class,
because it is an immediate action control with no associated value.
Example: object ctl; gCheckFunction(ctl, fun); |
See also: GetControl::Dialog
r = gCheckValue(ctl) object ctl; /* a control object */ int r; /* result of call */ |
This method is used to explicitly cause all error checking functions and
parameters associated with control ctl
to be checked. If an error
is encountered an appropriate error message will be displayed and a 1
will be returned. If no error is encountered a 0 is returned.
This method is implemented by all subclasses of Control
and mainly
used internally when the dialog is accepted.
Example: gCheckValue(ctl); |
See also: CheckFunction::Control
This method performs the same function as Dispose
. See that
method for details.
r = gDefaultProcessingMode(ctl, msg, mode); object ctl; /* a control object */ unsigned msg; /* message */ int mode; /* default processing mode */ object r; /* the control obj */ |
This method is used to determine when or if the Windows default message
procedure is processed for a given message (msg
) associated with
a particular control (ctl
).
WDS allows a programmer to specify an arbitrary number of functions
to be executed whenever a control receives a specific message (via
AddHandlerAfter
and AddHandlerBefore
). Windows has
default procedures associated with many control messages. At times
it is necessary to replace or augment this default functionality.
DefaultProcessingMode
gives the programmer control over when and
if this default Windows functionality. mode
is used to specify
the desired mode. The following table indicates the valid modes:
0
Do not execute the Windows default processing
1
Execute default processing after programmer defined handlers
2
Execute default processing before programmer defined handlers
Note that the default mode is always 1
, and must be explicitly
changed, if desired, for each message associated with each control.
msg
is the particular message you wish to affect. These messages
are fully documented in the Windows documentation in the Messages
section. They normally begin with WM_
.
Example: gDefaultProcessingMode(ctl, (unsigned) WM_SIZE, 0); |
See also: CallDefaultProc, AddHandlerAfter
r = gDispose(ctl); object ctl; /* a control object */ object r; /* NULL */ |
This method is used to remove and dispose of a control object when it is no longer needed. This method is rarely needed due to the fact that when a dialog is disposed it automatically calls this method on each of its associated controls.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object ctl; ctl = gDispose(ctl); |
See also: DeepDispose
h = gHandle(ctl); object ctl; /* control object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with
a control object. It will only return a valid handle while the dialog
is being performed via gPerform
. NULL
will be returned
otherwise.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object ctl; HANDLE h; h = gHandle(ctl); |
See also: GetControl::Dialog
pt = gSetTopic(ctl, tpc); object ctl; /* control object */ char *tpc; /* help topic */ char *pt; /* previous help topic */ |
This method is used to associate help text with specific control ctl
.
The help text is defined using the Windows help system and labeled
with the topic indicated by tpc
. Then, if the user hits
the F1 key while in the control, WDS will automatically bring up
the Windows help system and find the indicated topic. If no control
specific help is specified, WDS will use any help associated with the
dialog as a whole.
WDS also supports dialog and control specific topics. See the appropriate sections.
This method returns any previous topic associated with the control.
Example: object ctl; gSetTopic(ctl, "myControlHelp"); |
See also: The HelpSystem
class and SetTopic::Dialog
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The TextControl
class is a control which enables the user to
enter arbitrary alphanumeric data on a single line. This control
has numerous facilities to control the length and type of input the
user is allowed to enter.
The TextControl
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
value associated with a control object. val
should be an
instance of the String
class and will be automatically updated
to reflect the value associated with the control.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNew(String); gAttach(ctl, val); |
See also: Value, StringValue, SetValue
r = gCapitalize(ctl); object ctl; /* control object */ object r; /* control object */ |
This method is used to enable the auto-capitalize feature of the text control. If enabled, all alpha entry made by the user will be converted to upper case both on the display and internally to the control.
Example: object ctl; gCapitalize(ctl); |
See also: TextRange
r = gMaxLength(ctl, len); object ctl; /* control object */ int len; /* maximum length */ object r; /* control object */ |
This method is used to set the maximum number of characters the user may
enter into a text control. If the user attempts to enter more than
len
characters, including spaces, the system will just beep. If
the number of characters exceeds the field display width, the display
will scroll.
Example: object ctl; gMaxLength(ctl, 25); |
See also: MinLength, TextRange, Capitalize, CheckFunction::Control
r = gMinLength(ctl, len); object ctl; /* control object */ int len; /* minimum length */ object r; /* control object */ |
This method is used to set the minimum number of characters the user must
enter into a text control. If the user attempts to accept the dialog
without entering len
characters, including spaces, WDS will
issue an error message and return the user to the incomplete field.
Example: object ctl; gMinLength(ctl, 5); |
See also: MaxLength, TextRange, Capitalize, CheckFunction::Control
ctl = mNewCtl(TextControl, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(TextControl, PERSON_NAME); |
See also: AddControl::Dialog, GetControl::Dialog
r = gSetStringValue(ctl, val); object ctl; /* control object */ char *val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a pointer to a character string which represents
the desired value for the control.
Any previously associated value object will be disposed when the new value is set.
Example: object ctl; gSetStringValue(ctl, "Some value"); |
See also: SetValue, StringValue
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of the
String
class and initialized to the value desired for the control.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithStr(String, "Some value")); |
See also: SetStringValue, Value, Attach
val = gStringValue(ctl); object ctl; /* control object */ char *val; /* ctl value */ |
This method is used to obtain a C character pointer which represents the value associated with the control. This pointer will not be valid after the control or associated dialog are disposed.
Example: object ctl; char *val; val = gStringValue(ctl); |
See also: Value, Attach, SetStringValue, CtlStringValue::Dialog
r = gTextRange(ctl, min, max); object ctl; /* control object */ int min; /* minimum length */ int max; /* maximum length */ object r; /* control object */ |
This method is used to set the minimum number of characters the user must enter into a text control as well as the maximum number of characters allowed.
If the user attempts to enter more than max
characters, including
spaces, the system will just beep. If the number of characters exceeds
the field display width, the display will scroll.
If the user attempts to accept the dialog without entering min
characters, including spaces, WDS will issue an error message and return
the user to the incomplete field.
Example: object ctl; gTextRange(ctl, 5, 25); |
See also: MaxLength, MinLength, Capitalize, CheckFunction::Control
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the String
class. This object will be disposed by WDS when the
control object or associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: StringValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The NumericControl
class is a control which enables the user to
enter arbitrary numeric data. This control has numerous facilities to
control the range and type of input the user is allowed to enter.
The NumericControl
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
value associated with a control object. val
should be an
instance of one of the Dynace numeric classes which are subclasses of
the Number
class, such as ShortInteger
or
DoubleFloat
. This numeric object will be automatically updated
to reflect the value associated with the control.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithDouble(DoubleFloat, 0.0); gAttach(ctl, val); |
See also: Value, DoubleValue, ShortValue, SetValue
val = gDoubleValue(ctl); object ctl; /* control object */ double val; /* ctl value */ |
This method is used to obtain a C double which represents the value associated with the control.
Example: object ctl; double val; val = gDoubleValue(ctl); |
See also: Value, Attach, SetDoubleValue, CtlDoubleValue::Dialog
UnsignedShortValue, ShortValue, LongValue
val = gLongValue(ctl); object ctl; /* control object */ long val; /* ctl value */ |
This method is used to obtain a C long integer which represents the value associated with the control.
Example: object ctl; long val; val = gLongValue(ctl); |
See also: Value, Attach, SetLongValue, CtlLongValue::Dialog
UnsignedShortValue, ShortValue, DoubleValue
ctl = mNewCtl(NumericControl, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(NumericControl, PERSON_AGE); |
See also: AddControl::Dialog, GetControl::Dialog
r = gNumericRange(ctl, min, max, dp); object ctl; /* control object */ double min; /* minimum value */ double max; /* maximum value */ int dp; /* decimal places */ object r; /* control object */ |
This method is used to set the minimum and maximum allowable values the control will accept from the user. It also sets the number of digits to the right of the decimal point the control will accept.
If the user enters a number outside the specified range, WDS will issue an error message and prompt the user for an acceptable value.
Example: object ctl; gNumericRange(ctl, 5.0, 25.0, 1); |
See also: CheckFunction::Control
r = gSetDoubleValue(ctl, val); object ctl; /* control object */ double val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired value for
the control.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetDoubleValue(ctl, 3.14159265358979); |
See also: SetValue, DoubleValue, CtlDoubleValue::Dialog, SetUShortValue,
SetShortValue, SetLongValue
r = gSetLongValue(ctl, val); object ctl; /* control object */ long val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired value for
the control.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetLongValue(ctl, 66L); |
See also: SetValue, LongValue, CtlLongValue::Dialog, SetUShortValue,
SetShortValue, SetDoubleValue
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired value for
the control.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetShortValue(ctl, 66); |
See also: SetValue, ShortValue, CtlShortValue::Dialog, SetUShortValue,
SetLongValue, SetDoubleValue
r = gSetUShortValue(ctl, val); object ctl; /* control object */ unsigned val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired value for
the control.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetUShortValue(ctl, 66); |
See also: SetValue, UnsignedShortValue, CtlUnsignedShortValue::Dialog
SetShortValue, SetLongValue, SetDoubleValue
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of one of the
subclasses of the Number
class and initialized to the value
desired for the control.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithDouble(DoubleFloat, 3.141)); |
See also: Value, SetShortValue, SetUShortValue
SetLongValue, SetDoubleValue
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short integer which represents the value associated with the control.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: Value, Attach, SetShortValue, CtlShortValue::Dialog
UnsignedShortValue, LongValue, DoubleValue
val = gUnsignedShortValue(ctl); object ctl; /* control object */ unsigned short val; /* ctl value */ |
This method is used to obtain a C unsigned short integer which represents the value associated with the control.
Example: object ctl; unsigned short val; val = gUnsignedShortValue(ctl); |
See also: Value, Attach, SetUShortValue, CtlUnsignedShortValue::Dialog
ShortValue, LongValue, DoubleValue
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
one of the subclasses of the Number
class. This object will be
disposed by WDS when the control object or associated dialog is
disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, DoubleValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The DateControl
class is a control which enables the user to
enter date information. The user enters dates in the form mm/dd/yy
or mm/dd/yyyy, and when the user leaves the field it changes to the
form MMM DD, YYYY. For example, the user would enter 6/8/59 and
when the field is accepted it will be changed to display Jun 8, 1959.
Dates are stored internally as C longs in the form YYYYMMDD so that 6/8/59 would be represented as the long 19590608. This control has numerous facilities to control the range and type of input the user is allowed to enter.
The DateControl
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
value associated with a control object. val
should be an
instance of the Date
class. This date object will be
automatically updated to reflect the value associated with the control.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = vNew(Date, 0L); gAttach(ctl, val); |
See also: Value, LongValue, SetValue, SetLongValue
r = gDateRange(ctl, min, max, an); object ctl; /* control object */ long min; /* minimum value */ long max; /* maximum value */ int an; /* allow none */ object r; /* control object */ |
This method is used to set the minimum and maximum allowable values the control will accept from the user. It also controls whether or not the control will accept no date.
min
and max
are of the form YYYYMMDD. For example
6/8/59 would be represented as 19590608. If an
is 0
the user must enter a valid date between min
and max
.
If, however, an
is 1, the user must either enter a valid
date between the given ranges or may also leave the field blank.
If the user does not enter a date the field value will be 0L.
If the user enters an invalid date or one outside the specified range, WDS will issue an error message and prompt the user for an acceptable value.
Example: object ctl; gDateRange(ctl, 19990101L, 19991231L, 1); |
See also: CheckFunction::Control
val = gLongValue(ctl); object ctl; /* control object */ long val; /* ctl value */ |
This method is used to obtain a C long integer which represents the value associated with the control. It will be in the form YYYYMMDD. For example 6/8/59 would be represented as 19590608.
Example: object ctl; long val; val = gLongValue(ctl); |
See also: Value, Attach, SetLongValue, CtlLongValue::Dialog
ctl = mNewCtl(DateControl, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(DateControl, PERSON_BD); |
See also: AddControl::Dialog, GetControl::Dialog
r = gSetLongValue(ctl, val); object ctl; /* control object */ long val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired value for
the control of the form YYYYMMDD. For example 6/8/59 would be
19590608.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetLongValue(ctl, 19990101L); |
See also: SetValue, LongValue, CtlLongValue::Dialog
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of the
Date
class and initialized to the value desired for the control.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, vNew(Date, 19940101L)); |
See also: SetLongValue, Value
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the Date
class. This object will be disposed by WDS when the
control object or associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: LongValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The PushButton
class represents a control which allows the user
to perform an immediate action. That means that there is no particular
data associated with the control. The user pushes the button and an
associated action gets performed at that point. The PushButton
class allows the programmer to associate a C function to the control
such that whenever the user clicks on the button the specified function
will be evoked.
The PushButton
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
ctl = mNewCtl(PushButton, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(PushButton, MY_BUTTON); |
See also: AddControl::Dialog, GetControl::Dialog
r = gPerform(ctl); object ctl; /* control object */ int r; /* result */ |
This method is used to manually evoke the function a programmer associated with a push button. The value returned is the result of the function attached to the button.
This method is seldom needed because WDS automatically evokes the function when the user clicks the button.
Example: object ctl; gPerform(ctl); |
See also: SetFunction
r = gSetFunction(ctl, fun); object ctl; /* control object */ int (*fun)(); /* check function */ ofun r; /* previous check function */ |
This method is used to associate a C function to a push button such that if the user clicks the button the C function will immediately get evoked. The value returned is the previous function, if any, associated with the control.
The C function takes the following form:
int fun(object ctl, object dlg) { .... } |
Where ctl
is the control object, and dlg
is the object
representing the dialog the control is associated with. The value
returned by fun
only has meaning if the button was either
IDOK
or IDCANCEL
(the ones normally used to exit the
dialog). If the return value is 1 then the dialog will exit like normal.
If the return value is 0 then the dialog will not exit.
Example: object ctl; gSetFunction(ctl, fun); |
See also: Perform
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The CheckBox
class represents a control which allows the user
to select or de-select a particular option. Unlike radio buttons,
check boxes are not mutually exclusive.
The CheckBox
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
state associated with a control object. val
should be an
instance of the ShortInteger
class. This object will be
automatically updated to reflect the state associated with the control.
The object will represent 0 if the box is not checked, 1 if it is checked, or 2 if the box is grayed.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithInt(ShortInteger, 0); gAttach(ctl, val); |
See also: Value, ShortValue, SetValue, SetShortValue
ctl = mNewCtl(CheckBox, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(CheckBox, MY_CHECKBOX); |
See also: AddControl::Dialog, GetControl::Dialog
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired state associated
with the check box.
val
should be set to 0 to uncheck the box, 1 to check it, or 2 to
gray the box (only work on 3-state boxes).
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetShortValue(ctl, 1); |
See also: SetValue, ShortValue, CtlShortValue::Dialog
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of the
ShortInteger
class and initialized to the value desired for the
control.
val
should represent 0 to uncheck the box, 1 to check it, or 2 to
gray the box (only work on 3-state boxes).
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithInt(ShortInteger, 1)); |
See also: SetShortValue, Value
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short integer which represents the state associated with the control. The returned integer will be 0 if the box is not checked, 1 if it is checked, or 2 if the box is grayed.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: Value, Attach, SetShortValue, CtlShortValue::Dialog
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the ShortInteger
class. The returned object will represent 0 if
the box is not checked, 1 if it is checked, or 2 if the box is grayed.
This object will be disposed by WDS when the control object or
associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The RadioButton
class represents a control which allows the user
to select or de-select a particular option. Unlike check boxes, however,
radio buttons are mutually exclusive within a group - similar to the
buttons on old fashioned radios, when one button gets selected all the
other ones in the group get de-selected.
When using radio buttons, be sure to use the Group
function in order
to tell WDS which radio buttons should be grouped together.
The RadioButton
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
state associated with a control object. val
should be an
instance of the ShortInteger
class. This object will be
automatically updated to reflect the state associated with the control.
The object will represent 0 if the button is not selected, 1 if it is selected, or 2 if the button is grayed.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithInt(ShortInteger, 0); gAttach(ctl, val); |
See also: Value, ShortValue, SetValue, SetShortValue
r = mGroup(ctl, id1, id2); object ctl; /* control object */ unsigned id1; /* starting ctl id */ unsigned id2; /* ending ctl id */ object r; /* control object */ |
This method is used to tell WDS which radio buttons are to be considered
part of the same mutually exclusive group. id1
and id2
are the resource editor defined id’s associated with the beginning and
end of the group. WDS uses this information to automatically de-select
all radio buttons which are part of a group when one of the buttons is
selected.
Example: object ctl; mGroup(ctl, FIRST_RB, LAST_RB); |
ctl = mNewCtl(RadioButton, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(RadioButton, MY_RADIOBUTTON); |
See also: AddControl::Dialog, GetControl::Dialog, Group
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired state associated
with the radio button.
val
should be set to 0 to de-select the button, 1 to select it, or 2 to
gray the button (only work on 3-state buttons).
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetShortValue(ctl, 1); |
See also: SetValue, ShortValue, CtlShortValue::Dialog, Group
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of the
ShortInteger
class and initialized to the value desired for the
control.
val
should represent 0 to de-select the button, 1 to select it, or 2 to
gray the button (only work on 3-state buttons).
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithInt(ShortInteger, 1)); |
See also: SetShortValue, Value, Group
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short integer which represents the state associated with the control. The returned integer will be 0 if the button is not selected, 1 if it is selected, or 2 if the button is grayed.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: Value, Attach, SetShortValue, CtlShortValue::Dialog
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the ShortInteger
class. The returned object will represent 0 if
the button is not selected, 1 if it is selected, or 2 if the button is grayed.
This object will be disposed by WDS when the control object or
associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ListBox
class represents a control which allows the user
to select from a list of choices. These choices are presented in
a vertical, possibly drop down, list of text choices. This control
supports access to the user’s choice via the text option selected or
an ordinal value.
The application specifies, at runtime, the choices located in the list box.
The main difference between list boxes and combo boxes is that with list boxes the user can only select from the available choices, however, in addition, combo boxes allow the user to enter a choice independent of the available options.
The ListBox
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAddOption(ctl, op); object ctl; /* control object */ char *op; /* new option */ object r; /* control object */ |
This method is used to append a new option to the list of options associated
with a list box. This method may be used prior to or during the execution
(via gPerform
) of a dialog.
op
may also be a Dynace object, an instance of the String
class, representing the new choice. If a Dynace object is used, it must
be typecast to a string and it will be disposed when the control or
associated dialog are disposed.
Example: object ctl; gAddOption(ctl, "The first choice"); gAddOption(ctl, "The second choice"); |
See also: Alphabetize::ListBox, AddOptionAt::ListBox
r = gAlphabetize(ctl); object ctl; /* control object */ object r; /* control object */ |
This method is used to cause the automatic alphabetization of all
options added via the AddOption
method. In order to function
properly, Alphabetize
must be called prior to any calls to
AddOption
. This method simply returns the object passed.
See also: AddOption::ListBox
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
state associated with a control object. val
should be an
instance of the ShortInteger
class or the String
class.
This object will be automatically updated to reflect the state
associated with the control.
If val
is an instance of the ShortIntgeger
class it will
be used to represent the ordinal value of the selected item. This value
is a 0 based index from the top of the list to the bottom. -1 is used
to represent no valid selection.
If val
is an instance of the String
class it will be used
to represent the string represented by the user’s choice. If no choice is
made it will represent "".
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithInt(ShortInteger, 0); gAttach(ctl, val); |
See also: Value, ShortValue, StringValue
ary = gGetSelections(ctl); object ctl; /* control object */ object ary; /* array of selections */ |
This method is used to obtain an array representing the items selected
by the user. It is most useful with list boxes which have multi-selection
enabled. The array returned is an instance of the IntegerArray
class
and must be explicitly disposed when no longer needed. Each element
of the array represents a zero based index of one of the user’s selections,
and the size of the array represents the number of items selected.
This method may only be used while a dialog is active and will return
NULL
otherwise.
See also: ValueAt, NumbSelected, Value, ListIndex
val = gListIndex(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the ShortInteger
class. The returned object will represent the
ordinal value of the choice made by the user. This ordinal value is a
zero based index from top to bottom. -1 indicates that no choice was
made.
This object will be disposed by WDS when the control object or associated dialog is disposed.
Example: object ctl, val; val = gListIndex(ctl); |
See also: ShortValue, Value, StringValue, GetSelections, SetValue
ctl = mNewCtl(ListBox, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(ListBox, MY_LISTBOX); |
See also: AddControl::Dialog, GetControl::Dialog, AddOption
n = gNumbSelected(ctl); object ctl; /* control object */ int n; /* number selected */ |
This method is used to obtain the number of list box items the user
has selected. It is mainly used with multi-selection list boxes.
This method should only be used while the dialog is active and
will return -1 otherwise.
See also: GetSelections
r = gRemoveAll(ctl); object ctl; /* control object */ object r; /* control object */ |
This method is used to remove all items from a list box. It may be used
prior to or during the execution of a dialog. The control object passed
is returned.
See also: RemoveStr, RemoveInt
r = gRemoveInt(ctl, idx); object ctl; /* control object */ int idx; /* index */ object r; /* control object */ |
This method is used to remove an item from a list box while the dialog
is active. idx
is a zero based index of the item to be removed.
If the operation secceeded ctl
is returned, otherwise NULL
is returned.
This method may only be used while a dialog is active. It should not be
used prior to performing (via gPerform
) a dialog or after the user
has accepted or canceled the dialog.
Example: object ctl; gRemoveInt(ctl, 1); |
See also: RemoveStr, RemoveAll
r = gRemoveStr(ctl, itm); object ctl; /* control object */ char *itm; /* item */ object r; /* control object */ |
This method is used to remove an item from a list box while the dialog
is active. itm
is the string to be removed.
If the operation secceeded ctl
is returned, otherwise NULL
is returned.
This method may only be used while a dialog is active. It should not be
used prior to performing (gPerform
) a dialog or after the user
has accepted or canceled the dialog.
Example: object ctl; gRemoveStr(ctl, "Some Option"); |
See also: RemoveInt, FindMode
r = gRequired(ctl, mode); object ctl; /* control object */ int mode; /* required mode */ object r; /* control object */ |
This method is used to determine whether or not the user is required to make a valid selection prior to WDS allowing the acceptance of the dialog. If it is required and the user does not make a valid selection, WDS will issue an error message and return them to the control.
mode
is 1 to make it required and 0 otherwise.
Example: object ctl; gRequired(ctl, 1); |
See also: CheckFunction::Control, CheckValue::Control
r = gSetFunction(ctl, fun); object ctl; /* control object */ int (*fun)(); /* check function */ ofun r; /* previous check function */ |
This method is used to associate a C function to a list box such that if the user double clicks an item in the list box the C function will immediately get evoked. The value returned by this method is the function, if any, which was previously associated with the control.
The C function takes the following form:
int fun(object ctl, object dlg) { .... } |
Where ctl
is the control object, and dlg
is the object
representing the dialog the control is associated with. The value
returned by fun
is ignored.
Example: object ctl; gSetFunction(ctl, fun); |
See also: Perform, SetChgFunction
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the control. It is often used to set the initial value prior to performing a dialog.
val
will be used as the ordinal value of the selected item. This
value is a 0 based index from the top of the list to the bottom.
Any previously associated object (via Value
) will be disposed
when the new value is set.
Example: object ctl; gSetShortValue(ctl, 1); |
See also: SetStringValue, SetValue
r = gSetStringValue(ctl, val); object ctl; /* control object */ char *val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the control. It is often used to set the initial value prior to performing a dialog.
val
will be used to select the option which matches the string.
Any previously associated object (via val
) will be disposed when
the new value is set.
Example: object ctl; gSetStringValue(ctl, "The choice"); |
See also: SetShortValue, SetValue
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the
control. It is often used to set the initial value prior to performing
a dialog. val
should be a Dynace object which is an instance of
either the String
class or the ShortInteger
class and
initialized to the value desired for the control.
If val
is an instance of the ShortIntgeger
class it will be
used as the ordinal value of the selected item. This value is a 0 based
index from the top of the list to the bottom.
If val
is an instance of the String
class it will be used
to select the option which matches the string represented by val
.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithInt(ShortInteger, 1)); or gSetValue(ctl, gNewWithStr(String, "The choice")); |
See also: SetShortValue, SetStringValue
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short which represents the value associated with the control. The returned value will represent the ordinal value of the choice made by the user. This ordinal value is a zero based index from top to bottom. -1 indicates that no choice was made.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: ListIndex, Value, GetSelections, StringValue, SetValue
val = gStringValue(ctl); object ctl; /* control object */ char *val; /* ctl value */ |
This method is used to obtain a character string pointer which represents the value associated with the control. The returned pointer will represent the text associated with the user selected choices. It will point to "" if the user had not made a valid selection.
The returned pointer will not be valid once the control object or associated dialog is disposed.
Example: object ctl; char *val; val = gStringValue(ctl); |
See also: ShortValue, Value, ListIndex, GetSelections, SetValue
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the String
class. The returned object will represent the text
associated with the user selected choices. If no selection was made
the object will represent "".
This object will be disposed by WDS when the control object or associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, StringValue, ValueAt, ListIndex, GetSelections, SetValue
val = gValueAt(ctl, idx); object ctl; /* control object */ int idx; /* index */ object val; /* value at idx */ |
This method is used to obtain a Dynace object which represents the text
associated with the line indexed by the zero based index idx
.
The object returned will be an instance of the String
class. If
the index is out of range this method will return NULL
.
This method may only be called when the dialog is active. The object
returned must be explicitly disposed when no longer needed.
See also: ShortValue, Value, ListIndex, GetSelections, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ComboBox
class represents a control which allows the user to
select from a list of choices or enter an alternate text string. These
choices are presented in a vertical, possibly drop down, list of text
choices. This control supports access to the user’s choice via the text
option selected or an ordinal value.
The application specifies, at runtime, the choices located in the list box.
The main difference between list boxes and combo boxes is that with list boxes the user can only select from the available choices, however, in addition, combo boxes allow the user to enter a choice independent of the available options.
The ComboBox
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAddEdtHandlerAfter(ctl, msg, func); object ctl; /* a control object */ unsigned msg; /* message */ long (*func)(); /* function pointer */ object r; /* the control obj */ |
This method is used to associate function func
with the text
entry window portion of the combo box, message msg
for
control ctl
. Whenever the text entry window of control
ctl
receives message msg
, func
will be called.
ctl
is the control object who’s text window messages you wish to
process. msg
is the particular message you wish to trap. These
messages are fully documented in the Windows documentation in the
Messages section. They normally begin with WM_
.
func
is the function which gets called whenever the specified
message gets received and takes the following form:
long func(object ctl, HWND hwnd, UINT mMsg, WPARAM wParam, LPARAM lParam) { . . . return 0L; /* or whatever is appropriate */ } |
Where ctl
is the control being sent the message. The remaining
arguments and return value is fully documented in the Windows documentation
under the WindowProc
function and the Windows Messages documentation.
WDS keeps a list of functions associated with each message associated
with each control. When a particular message is received the appropriate
list of handler functions gets executed sequentially.
AddEdtHandlerAfter
appends the new function to the end of this list,
and AddEdtHandlerBefore
adds the new function to the beginning of
the list.
WDS may also, and optionally, execute the Windows default procedure
associated with a given message either before or after the user added
list of functions. This behavior may be controlled via
DefaultEdtProcessingMode
.
Windows will only see the return value of the last message handler executed including, if applicable, the default.
Example: int hSize, vSize; static long process_wm_size(object ctl, HWND hwnd, UINT mMsg, WPARAM wParam, LPARAM lParam) { hSize = LOWORD(lParam); vSize = HIWORD(lParam); return 0L; } . . gAddEdtHandlerAfter(ctl, (unsigned) WM_SIZE, process_wm_size); . . |
See also: DefaultProcessingMode, AddEdtHandlerBefore,
AddHandlerAfter::Control
r = gAddEdtHandlerBefore(ctl, msg, func); object ctl; /* a control object */ unsigned msg; /* message */ long (*func)(); /* function pointer */ object r; /* the control obj */ |
This function is fully documented under AddEdtHandlerAfter
.
See also: AddEdtHandlerAfter, AddHandlerAfter::Control
r = gAddOption(ctl, op); object ctl; /* control object */ char *op; /* new option */ object r; /* control object */ |
This method is used to append a new option to the list of options associated
with a combo box. This method may be used prior to or during the execution
(via gPerform
) of a dialog.
op
may also be a Dynace object, an instance of the String
class, representing the new choice. If a Dynace object is used, it must
be typecast to a string and it will be disposed when the control or
associated dialog are disposed.
Example: object ctl; gAddOption(ctl, "The first choice"); gAddOption(ctl, "The second choice"); |
See also: Alphabetize::ComboBox, AddOptionAt::ComboBox
r = gAlphabetize(ctl); object ctl; /* control object */ object r; /* control object */ |
This method is used to cause the automatic alphabetization of all
options added via the AddOption
method. In order to function
properly, Alphabetize
must be called prior to any calls to
AddOption
. This method simply returns the object passed.
See also: AddOption::ComboBox
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
state associated with a control object. val
should be an
instance of the ShortInteger
class or the String
class.
This object will be automatically updated to reflect the state
associated with the control.
If val
is an instance of the ShortIntgeger
class it will
be used to represent the ordinal value of the selected item. This value
is a 0 based index from the top of the list to the bottom. -1 is used
to represent no valid selection.
If val
is an instance of the String
class it will be used
to represent the string represented by the user’s choice. If no choice is
made it will represent "".
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithInt(ShortInteger, 0); gAttach(ctl, val); |
See also: Value, ShortValue, StringValue
r = gDefaultEdtProcessingMode(ctl, msg, mode); object ctl; /* a control object */ unsigned msg; /* message */ int mode; /* default processing mode */ object r; /* the control obj */ |
This method is used to determine when or if the Windows default message
procedure is processed for a given message (msg
) associated with
the text entry window portion of control (ctl
).
WDS allows a programmer to specify an arbitrary number of functions to
be executed whenever the text entry portion of a combo box control
receives a specific message (via AddEdtHandlerAfter
and
AddEdtHandlerBefore
). Windows has default procedures associated
with many control messages. At times it is necessary to replace or
augment this default functionality. DefaultEdtProcessingMode
gives the programmer control over when and if this default Windows
functionality. mode
is used to specify the desired mode. The
following table indicates the valid modes:
0
Do not execute the Windows default processing
1
Execute default processing after programmer defined handlers
2
Execute default processing before programmer defined handlers
Note that the default mode is always 1
, and must be explicitly
changed, if desired, for each message associated with each control.
msg
is the particular message you wish to affect. These messages
are fully documented in the Windows documentation in the Messages
section. They normally begin with WM_
.
Example: gDefaultEdtProcessingMode(ctl, (unsigned) WM_SIZE, 0); |
See also: AddEdtHandlerAfter
val = gListIndex(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the ShortInteger
class. The returned object will represent the
ordinal value of the choice made by the user. This ordinal value is a
zero based index from top to bottom. -1 indicates that no choice was
made.
This object will be disposed by WDS when the control object or associated dialog is disposed.
Example: object ctl, val; val = gListIndex(ctl); |
See also: ShortValue, Value, StringValue, Attach, SetValue
ctl = mNewCtl(ComboBox, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(ComboBox, MY_COMBOBOX); |
See also: AddControl::Dialog, GetControl::Dialog, AddOption
r = gRemoveAll(ctl); object ctl; /* control object */ object r; /* control object */ |
This method is used to remove all items from a combo box. It may be used
prior to or during the execution of a dialog. The control object passed
is returned.
See also: RemoveStr, RemoveInt
r = gRemoveInt(ctl, idx); object ctl; /* control object */ int idx; /* index */ object r; /* control object */ |
This method is used to remove an item from a combo box while the dialog
is active. idx
is a zero based index of the item to be removed.
If the operation secceeded ctl
is returned, otherwise NULL
is returned.
This method may only be used while a dialog is active. It should not be
used prior to performing (gPerform
) a dialog or after the user
has accepted or canceled the dialog.
Example: object ctl; gRemoveInt(ctl, 1); |
See also: RemoveStr, RemoveAll
r = gRemoveStr(ctl, itm); object ctl; /* control object */ char *itm; /* item */ object r; /* control object */ |
This method is used to remove an item from a combo box while the dialog
is active. itm
is the string to be removed.
If the operation secceeded ctl
is returned, otherwise NULL
is returned.
This method may only be used while a dialog is active. It should not be
used prior to performing (gPerform
) a dialog or after the user
has accepted or canceled the dialog.
Example: object ctl; gRemoveStr(ctl, "Some Option"); |
See also: RemoveInt::ComboBox, FindMode::ComboBox
r = gRequired(ctl, mode); object ctl; /* control object */ int mode; /* required mode */ object r; /* control object */ |
This method is used to determine whether or not the user is required to make a valid selection prior to WDS allowing the acceptance of the dialog. If it is required and the user does not make a valid selection, WDS will issue an error message and return them to the control.
mode
is 1 to make it required and 0 otherwise.
Example: object ctl; gRequired(ctl, 1); |
See also: CheckFunction::Control, CheckValue::Control
r = gSetFunction(ctl, fun); object ctl; /* control object */ int (*fun)(); /* check function */ ofun r; /* previous check function */ |
This method is used to associate a C function to a combo box such that if the user double clicks an item in the combo box the C function will immediately get evoked. The value returned by this method is the function, if any, which was previously associated with the control.
The C function takes the following form:
int fun(object ctl, object dlg) { .... } |
Where ctl
is the control object, and dlg
is the object
representing the dialog the control is associated with. The value
returned by fun
is ignored.
Example: object ctl; gSetFunction(ctl, fun); |
See also: Perform, SetChgFunction
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the control. It is often used to set the initial value prior to performing a dialog.
val
will be used as the ordinal value of the selected item. This
value is a 0 based index from the top of the list to the bottom.
Any previously associated object (via Value
) will be disposed
when the new value is set.
Example: object ctl; gSetShortValue(ctl, 1); |
See also: SetStringValue, SetValue
r = gSetStringValue(ctl, val); object ctl; /* control object */ char *val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the control. It is often used to set the initial value prior to performing a dialog.
val
will be used to select the option which matches the string.
Any previously associated object (via val
) will be disposed when
the new value is set.
Example: object ctl; gSetStringValue(ctl, "The choice"); |
See also: SetShortValue, SetValue
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the default selection associated with the
control. It is often used to set the initial value prior to performing
a dialog. val
should be a Dynace object which is an instance of
either the String
class or the ShortInteger
class and
initialized to the value desired for the control.
If val
is an instance of the ShortIntgeger
class it will be
used as the ordinal value of the selected item. This value is a 0 based
index from the top of the list to the bottom.
If val
is an instance of the String
class it will be used
to select the option which matches the string represented by val
.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithInt(ShortInteger, 1)); or gSetValue(ctl, gNewWithStr(String, "The choice")); |
See also: SetShortValue, SetStringValue
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short which represents the value associated with the control. The returned value will represent the ordinal value of the choice made by the user. This ordinal value is a zero based index from top to bottom. -1 indicates that no choice was made.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: ListIndex, Value, StringValue, Attach, SetValue
val = gStringValue(ctl); object ctl; /* control object */ char *val; /* ctl value */ |
This method is used to obtain a character string pointer which represents the value associated with the control. The returned pointer will represent the text associated with the user selected choices. It will point to "" if the user had not made a valid selection.
The returned pointer will not be valid once the control object or associated dialog is disposed.
Example: object ctl; char *val; val = gStringValue(ctl); |
See also: ShortValue, Value, ListIndex, Attach, SetValue
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the String
class. The returned object will represent the text
associated with the user selected choices. If no selection was made
the object will represent "".
This object will be disposed by WDS when the control object or associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, StringValue, ValueAt, ListIndex, Attach, SetValue
val = gValueAt(ctl, idx); object ctl; /* control object */ int idx; /* index */ object val; /* value at idx */ |
This method is used to obtain a Dynace object which represents the text
associated with the line indexed by the zero based index idx
.
The object returned will be an instance of the String
class. If
the index is out of range this method will return NULL
.
This method may only be called when the dialog is active. The object
returned must be explicitly disposed when no longer needed.
See also: ShortValue, Value, ListIndex, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ScrollBar
class represents a control which allows the user to
select a number between two ranges via a linear, visually intuitive
control. The range defaults to 0 to 100 and may be controlled via
ScrollBarRange
.
The ScrollBar
class is a subclass of Control
and as such
inherits all the functionality associated with that class. This section
only documents functionality particular to this class.
Standard control arguments are documented in the section entitled “Standard Control Method Arguments”.
r = gAttach(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to associate an independent Dynace object with the
state associated with a control object. val
should be an
instance of the ShortInteger
class. This object will be
automatically updated to reflect the position of the scroll bar.
This object (val
) will never be disposed by WDS, even after
the control or associated dialog are disposed. Therefore, this
is one way of gaining access to a control’s value after the life
of the control. It is the programmer’s responsibility to dispose of
the object when it is no longer needed.
Example: object ctl, val; val = gNewWithInt(ShortInteger, 0); gAttach(ctl, val); |
See also: Value, ShortValue, SetValue, SetShortValue,
ScrollBarRange
r = gIncrement(ctl, val); object ctl; /* control object */ int val; /* increment value */ object r; /* control object */ |
This method is used to increment the position of the scroll bar
val
points from its current position. val
may
be negative or positive, which will determine the direction of movement.
Example: object ctl; gIncrement(ctl, 10); |
See also: SetShortValue, SetValue, ScrollBarRange
ctl = mNewCtl(ScrollBar, id); unsigned id; /* control id */ object ctl; /* control object */ |
This method is used to create a new control object to be identified as
id
(see section “Standard Control Method Arguments”). This
method is mainly used internally. A programmer would more often
use AddControl::Dialog
to create controls and associated them
to a dialog.
Example: object ctl; ctl = mNewCtl(ScrollBar, MY_SCROLLBAR); |
See also: AddControl::Dialog, GetControl::Dialog
r = gScrollBarRange(ctl, min, max, pginc, lininc) object ctl; /* control object */ int min; /* minimum range */ int max; /* maximum range */ int pginc; /* page increment */ int lineinc;/* line increment */ object r; /* control object */ |
This method is used to control the range and scrolling characteristics associated with a given scroll bar control.
min
and max
are used to determine the range of the
control. These are the values which are returned when the control
is at either end of its extremes. The default values are 0 and
100 respectively.
pginc
is used to control exactly how much the position of the
scroll bar will change when the user clicks the control in such a way
as to cause a page jump in the position. This is normally done by
clicking in the area on either side of position indicating element of the
control. The default value for the variable is 10. It must be less than
the difference between max
and min
, and is normally larger
than lineinc
.
lineinc
us used to control exactly how much the position of the
scroll bar will change when the user clicks the line increment arrows
located on the extreme ends of the control. The default value of this
control is 2.
Example: object ctl; gScrollBarRange(ctl, 0, 100, 10, 2); |
r = gSetShortValue(ctl, val); object ctl; /* control object */ int val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be the value which represents the desired
position of the scroll bar. It must be between the minimum and
maximum range associated with the control.
Any previously associated value object (associated via SetValue
)
will be disposed when the new value is set.
Example: object ctl; gSetShortValue(ctl, 50); |
See also: SetValue, Increment, CtlShortValue::Dialog,
ScrollBarRange
r = gSetValue(ctl, val); object ctl; /* control object */ object val; /* ctl value */ object r; /* control object */ |
This method is used to set the value associated with a control. It is
often used to set the initial value prior to performing a dialog.
val
should be a Dynace object which is an instance of the
ShortInteger
class and initialized to the value desired for the
control.
val
must represent a number between the minimum and maximum range
associated with the scroll bar.
Any previously associated object will be disposed when the new value is set.
Also, val
will automatically be disposed when the control or associated
dialog is disposed.
Example: object ctl; gSetValue(ctl, gNewWithInt(ShortInteger, 50)); |
See also: SetShortValue, Increment, Value, ScrollBarRange
val = gShortValue(ctl); object ctl; /* control object */ short val; /* ctl value */ |
This method is used to obtain a C short integer which represents the
position of the scroll bar. The returned value will represent the
position of the scroll bar control. This number will be between the
minimum and maximum range associated with the control via
ScrollBarRange
.
Example: object ctl; short val; val = gShortValue(ctl); |
See also: Value, Attach, SetShortValue, CtlShortValue::Dialog
val = gValue(ctl); object ctl; /* control object */ object val; /* ctl value */ |
This method is used to obtain a Dynace object which represents the value
associated with the control. The object returned will be an instance of
the ShortInteger
class. The returned object will represent
the position of the scroll bar control. This number will be between
the minimum and maximum range associated with the control via
ScrollBarRange
.
This object will be disposed by WDS when the control object or associated dialog is disposed.
Example: object ctl, val; val = gValue(ctl); |
See also: ShortValue, Attach, SetValue
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Cursor
class (as well as its subclasses) are used to represent
cursor objects. This class is never used by an application. It is used
to house the functionality common to its subclasses. Therefore, this
class documents functionality which is common to all of its subclasses.
Note that a more convenient mechanism for using cursors is provided by
LoadCursor::Window
and LoadSystemCursor::Window
c = gCopy(csr); object csr; /* cursor object */ object c; /* copy of cursor object */ |
This method is used to create a new cursor object which is a copy of a given cursor object. The value of this is to be able to associate a cursor with multiple objects which will automatically dispose of the cursor when they are disposed. If copies weren’t used the second object referencing the cursor would reference a disposed cursor object.
Each cursor object must be disposed (either automatically or manually) when it is no longer needed.
Example: object c1, c2; c2 = gCopy(c1); |
See also: DeepCopy
This method performs the same function as Copy
. See that
method for details.
This method performs the same function as Dispose
. See that
method for details.
r = gDispose(csr); object csr; /* a cursor object */ object r; /* NULL */ |
This method is used to dispose of a cursor object when it is no longer needed. This method is rarely needed due to the fact that when a window is disposed it automatically calls this method to dispose of its associated cursor object.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object csr; csr = gDispose(csr); |
See also: DeepDispose
h = gHandle(csr); object csr; /* cursor object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with a cursor object.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object csr; HCURSOR h; h = gHandle(csr); |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The SystemCursor
class represents Windows predefined cursors.
This class is a subclass of Cursor
and as such inherits most
of its functionality from it. This section documents the methods
particular to this class. See the Cursor
class for additional
functionality.
csr = gLoadSys(SystemCursor, id); char *id; /* cursor id */ object csr; /* cursor object */ |
This method is used to create a new object which represents one of the
Windows predefined cursors. id
should be one of the Windows
defined macros specifying the desired cursor. It is defined in the
Windows documentation under the function LoadCursor
and
starts with IDC_
.
Example: object csr; csr = gLoadSys(SystemCursor, IDC_IBEAM); |
See also: LoadSystemCursor::Window, SetCursor::Application
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ExternalCursor
class represents arbitrary application defined
cursors. This class is a subclass of Cursor
and as such inherits
most of its functionality from it. This section documents the methods
particular to this class. See the Cursor
class for additional
functionality.
csr = mLoad(ExternalCursor, id); unsigned id; /* cursor id */ object csr; /* cursor object */ |
This method is used to load a programmer defined application specific cursor.
id
is a programmer defined unsigned integer which identifies
the cursor. This identifier is normally a macro and defined through the
resource editor.
The value returned is an object representing the cursor loaded, or
NULL
if the cursor was not found.
Example: object csr; csr = mLoad(ExternalCursor, MY_CURSOR); |
See also: LoadCursor::Window, SetCursor::Application
csr = mLoadStr(ExternalCursor, id); char *id; /* cursor id */ object csr; /* cursor object */ |
This method is used to load a programmer defined application specific cursor by name.
id
is a programmer defined name which identifies the cursor.
This identifier is normally defined through the resource editor.
The value returned is an object representing the cursor loaded, or
NULL
if the cursor was not found.
Example: object csr; csr = mLoadStr(ExternalCursor, "mycursor"); |
See also: LoadCursor::Window, SetCursor::Application,
Use::Window
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Icon
class (as well as its subclasses) are used to represent
icon objects. This class is never used by an application. It is used
to house the functionality common to its subclasses. Therefore, this
class documents functionality which is common to all of its subclasses.
Note that a more convenient mechanism for using icons is provided by
LoadIcon::Window
and LoadSystemIcon::Window
c = gCopy(icn); object icn; /* icon object */ object c; /* copy of icon object */ |
This method is used to create a new icon object which is a copy of a given icon object. The value of this is to be able to associate a icon with multiple objects which will automatically dispose of the icon when they are disposed. If copies weren’t used the second object referencing the icon would reference a disposed icon object.
Each icon object must be disposed (either automatically or manually) when it is no longer needed.
Example: object i1, i2; i2 = gCopy(i1); |
See also: DeepCopy
This method performs the same function as Copy
. See that
method for details.
This method performs the same function as Dispose
. See that
method for details.
r = gDispose(icn); object icn; /* an icon object */ object r; /* NULL */ |
This method is used to dispose of an icon object when it is no longer needed. This method is rarely needed due to the fact that when a window is disposed it automatically calls this method to dispose of its associated icon object.
The value returned is always NULL
and may be used to null out
the variable which contained the object being disposed in order to
avoid future accidental use.
Example: object icn; icn = gDispose(icn); |
See also: DeepDispose
h = gHandle(icn); object icn; /* icon object */ HANDLE h; /* Windows handle */ |
This method is used to obtain the Windows internal handle associated with an icon object.
Note that this method may be used with most WDS objects in order to obtain the internal handle that Windows normally associates with each type of object. See the appropriate documentation.
Example: object icn; HICON h; h = gHandle(icn); |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The SystemIcon
class represents Windows predefined icons.
This class is a subclass of Icon
and as such inherits most
of its functionality from it. This section documents the methods
particular to this class. See the Icon
class for additional
functionality.
icn = gLoadSys(SystemIcon, id); char *id; /* icon id */ object icn; /* icon object */ |
This method is used to create a new object which represents one of the
Windows predefined icons. id
should be one of the Windows
defined macros specifying the desired icon. It is defined in the
Windows documentation under the function LoadIcon
and
starts with IDI_
.
Example: object icn; icn = gLoadSys(SystemIcon, IDI_HAND); |
See also: LoadSystemIcon::Window, SetIcon::Application
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ExternalIcon
class represents arbitrary application defined
icons. This class is a subclass of Icon
and as such inherits
most of its functionality from it. This section documents the methods
particular to this class. See the Icon
class for additional
functionality.
icn = mLoad(ExternalIcon, id); unsigned id; /* icon id */ object icn; /* icon object */ |
This method is used to load a programmer defined application specific icon.
id
is a programmer defined unsigned integer which identifies
the icon. This identifier is normally a macro and defined through the
resource editor.
The value returned is an object representing the icon loaded, or
NULL
if the icon was not found.
Example: object icn; icn = mLoad(ExternalIcon, MY_ICON); |
See also: LoadIcon::Window, SetIcon::Application
icn = mLoadStr(ExternalIcon, id); char *id; /* icon id */ object icn; /* icon object */ |
This method is used to load a programmer defined application specific icon by name.
id
is a programmer defined name which identifies the icon.
This identifier is normally defined through the resource editor.
The value returned is an object representing the icon loaded, or
NULL
if the icon was not found.
Example: object icn; icn = mLoadStr(ExternalIcon, "myicon"); |
See also: LoadIcon::Window, SetIcon::Application,
Use::Window
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Font
class (as well as its subclasses) are used to represent
font objects. This class is never used by an application. It is used
to house the functionality common to its subclasses. Therefore, this
class documents functionality which is common to all of its subclasses.
Note that a more convenient mechanism for using fonts is provided by
LoadFont::Window, LoadSystemFont::Window, LoadFont::Printer
,
and LoadSystemFont::Printer
.
r = gAveCharWidth(fnt); object fnt; /* a font object */ int r; /* ave char width */ |
This method is used to gain access to the average character width associated with a particular font.
Example: object fnt; int cw; cw = gAveCharWidth(fnt); |
See also: LineHeight, GetTM
c = gCopy(fnt); object fnt; /* font object */ object c; /* copy of font object */ |
This method is used to create a new font object which is a copy of a given font object. The value of this is to be able to associate a font with multiple objects which will automatically dispose of the font when they are disposed. If copies weren’t used the second object referencing the font would reference a disposed font object.
Each font object must be disposed (either automatically or manually) when it is no longer needed.
Example: object f1, f2; f2 = gCopy(f1); |
See also: DeepCopy
This method performs the same function as Copy
. See that
method for details.
This method performs the same function as Dispose
. See that
method for details.
r = gDispose(fnt); object fnt; /* a font object */ object r; /* NULL */ |