1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
|
</R>Purpose<!R>
The Cdk Dialog widget allows the user to pick from a number of options
using buttons provided. The dialog box presents a message, and a list of
options using the buttons.
</R>Construction Options<!R>
A dialog widget is defined using the following syntax. The variable
</B>$dialogObject<!B> contains the reference to the dialog object.
<C></B>$dialogObject = new Cdk::Dialog ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Mesg Required List Ref This is the message which is displayed
in the dialog box.
Buttons Required List Ref This is a list of the button labels.
Xpos Center Scalar This is the position of the window on
the X axis.
Ypos Center Scalar This is the position of the window on
the Y axis.
Highlight Reverse Scalar The highlight attribute of the
currently selected button.
Separator True Scalar This Boolean value states whether a
separator will be drawn between the
message and the buttons.
Box True Scalar This Boolean states whether the dialog
box will have a box drawn around it.
Shadow False Scalar This Boolean states whether the dialog
box will have a shadow on the box.
</R>Available Methods<!R>
</B>activate<!B>
Activation of an object means to make the object available for use. The
following example demonstrates how to activate a dialog widget.
<C></B>$returnValue = $dialogObject->activate ();
The variable </B>$returnValue<!B> contains an integer value representing which
button was actually selected. The value starts at zero and goes up.
</B>inject<!B>
This function injects a single character into the widget. The following
examples demonstrates how to call the inject method.
<C></B>$dialogObject->inject ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Shadow Required Scalar The character to inject into the widget.
If you are injecting a special character into the widget, then you can
use a pre-defined value to represent the key.
<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL></U>Key <#VL>Key Value <!U><#VL>
<C><#VL>Left Arrow <#VL>KEY_LEFT <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT <#VL>
<C><#VL>Up Arrow <#VL>KEY_UP <#VL>
<C><#VL>Down Arrow <#VL>KEY_DOWN <#VL>
<C><#VL>Delete <#VL>KEY_DELETE <#VL>
<C><#VL>Backspace <#VL>KEY_BACKSPACE <#VL>
<C><#VL>Page Up <#VL>KEY_PPAGE <#VL>
<C><#VL>Page Down <#VL>KEY_NPAGE <#VL>
<C><#VL>Home <#VL>KEY_HOME <#VL>
<C><#VL>End <#VL>KEY_END <#VL>
<C><#VL>Escape <#VL>KEY_ESC <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>
</B>set<!B>
Sets or resets certain attributes or features of the widget. The following
example demonstrates how to call the set method.
<C></B>$dialogObject->set ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Highlight Required Scalar Changes the current highlight attribute.
Separator Required Scalar Changes the current value for the
separator flag.
Box True Scalar Changes the current value for the box
flag.
</B>draw<!B>
This method draws the object on the screen. The following example
demonstrates how to call the draw method.
<C></B>$dialogObject->draw ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Box True Scalar Draws the window with a box.
</B>erase<!B>
This method removes the object from the screen. This does </B/U>NOT<!B!U> destroy
the object. The following example demonstrates how to call the erase
method.
<C></B>$dialogObject->erase ();
</B>bind<!B>
The bind method binds keys to events. The binding is specific to the
individual objects. The following example demonstrates how to call the
bind method.
<C></B>$dialogObject->bind ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Key Required Scalar This is the character to bind the
event to.
Function Required Scalar This is the name of the callback
function.
</B>preProcess<!B>
The </B>preProcess<!B> function sets a process to be run before the key entered
is processed. If this function returns a value of 0, then the key injected
into the widget will not be processed; otherwise the character will be
processed as normal. The following example demonstrates how to call the
preProcess method.
<C></B>$dialogObject->preProcess ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Function Required Scalar This is the name of the
callback function.
To create a pre-process callback the following code segment demonstrates
how to do it properly.
<C></B>$alphalistObject->preProcess ('Function' => sub { callback (@_); });
Notice that the array </B>@_<!B> is passed into the function called
</B>callback<!B>. This is done because when the callback process is
called the key which was pressed is passed into the perl subroutine.
Since we nest the call-back function inside an anonymous subroutine,
we need to pass the array </B>@_<!B> to the call-back function. If
the key given to the call-back function is a non alphanumeric key
then a predefined value will be given to the function. The following
table describes the values passed into the function.
<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL></U>Key <#VL>Key Value <!U><#VL>
<C><#VL>Left Arrow <#VL>KEY_LEFT <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT <#VL>
<C><#VL>Up Arrow <#VL>KEY_UP <#VL>
<C><#VL>Down Arrow <#VL>KEY_DOWN <#VL>
<C><#VL>Delete <#VL>KEY_DELETE <#VL>
<C><#VL>Backspace <#VL>KEY_BACKSPACE <#VL>
<C><#VL>Page Up <#VL>KEY_PPAGE <#VL>
<C><#VL>Page Down <#VL>KEY_NPAGE <#VL>
<C><#VL>Home <#VL>KEY_HOME <#VL>
<C><#VL>End <#VL>KEY_END <#VL>
<C><#VL>Escape <#VL>KEY_ESC <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>
If the pre-process function returns a value of 0 the key hit will
not be injected into the widget. This allows the programmer to
selectively pick which characters will or will not get injected
into the widget.
The </B>postProcess<!B> function sets a process to be run before the key entered
is processed. If this function returns a value of 0, then the key injected
into the widget will not be processed; otherwise the character will be
processed as normal. The following example demonstrates how to call the
postProcess method.
<C></B>$dialogObject->postProcess ( options );
The options are defined in the following table.
</U>Option Default Value Type Purpose<!U>
Function Required Scalar This is the name of the
callback function.
To create a post-process callback the following code segment demonstrates
how to do it properly.
<C></B>$alphalistObject->postProcess ('Function' => sub { callback (@_); });
Notice that the array </B>@_<!B> is passed into the function called
</B>callback<!B>. This is done because when the callback process is
called the key which was pressed is passed into the perl subroutine.
Since we nest the call-back function inside an anonymous subroutine,
we need to pass the array </B>@_<!B> to the call-back function. If
the key given to the call-back function is a non alphanumeric key
then a predefined value will be given to the function. The following
table describes the values passed into the function.
<C><#UL><#HL(12)><#TT><#HL(15)><#UR>
<C><#VL></U>Key <#VL>Key Value <!U><#VL>
<C><#VL>Left Arrow <#VL>KEY_LEFT <#VL>
<C><#VL>Right Arrow <#VL>KEY_RIGHT <#VL>
<C><#VL>Up Arrow <#VL>KEY_UP <#VL>
<C><#VL>Down Arrow <#VL>KEY_DOWN <#VL>
<C><#VL>Delete <#VL>KEY_DELETE <#VL>
<C><#VL>Backspace <#VL>KEY_BACKSPACE <#VL>
<C><#VL>Page Up <#VL>KEY_PPAGE <#VL>
<C><#VL>Page Down <#VL>KEY_NPAGE <#VL>
<C><#VL>Home <#VL>KEY_HOME <#VL>
<C><#VL>End <#VL>KEY_END <#VL>
<C><#VL>Escape <#VL>KEY_ESC <#VL>
<C><#LL><#HL(12)><#BT><#HL(15)><#LR>
</B>raise<!B>
The raise method raises the widget to the top of the screen. This means if
there were any widgets obscuring part of the view, raising the object would
bring the complete object into view. The following example demonstrates how
to call the raise method.
<C></B>$dialogObject->raise();
</B>lower<!B>
The lower method lowers the object so it doesn't obscure the view of any
other objects. The following example demonstrates how to call the lower
method.
<C></B>$dialogObject->lower();
</B>register<!B>
The register method registers the object to the default screen. This does </R>NOT<!R>
have to be called since the objects are registered automatically. This method
should be called if the </B>unregister<!B> method was called. The following
example demonstrates how to call the register method.
<C></B>$dialogObject->register();
</B>unregister<!B>
The unregister method should be called when a widget, which is part of the
default screen, needs to be taken away temporarily. This does not delete or
free the object, it just unmaps it from any future screen refreshes. The
object can be registered by calling the </B>register<!B> method. The
following example demonstrates how to call the unregister method.
<C></B>$dialogObject->unregister();
</B>getwin<!B>
This method returns a pointer to the window of the object. Not much use for
this yet. It will be useful in the future when the drawing methods are added.
The following example demonstrates how to call the getwin method.
<C></B>$dialogObject->getwin();
</R>Default Key Bindings<!R>
</U>Key Action<!U>
Left Arrow Highlights the button to the left of the currently
highlighted button.
Right Arrow Highlights the button to the right of the currently
highlighted button.
Space Highlights the button to the right of the currently
highlighted button.
Return Exits the widget and returns a value representing the
selected button. The range of the value is from 0 to
the number of buttons -1.
Tab Exits the widget and returns a value representing the
selected button. The range of the value is from 0 to
the number of buttons -1.
Escape Exits the dialog widget and returns undef.
CTRL-R Refreshes the screen.
</R>Tips & Tricks<!R>
<B=*>If you pass the dialog with no message and no separator, the
dialog box appears be a tool bar.
</R>Physical Restrictions<!R>
</U>Restriction Value<!U>
Maximum message rows. 50
Maximum dialog buttons. 25
</R>Example Use Of The Widget<!R>
<F=../examples/dialog>
<C><#HL(70)>
<C>Document Created: June, 1995
<C>Document Revised: November, 1995
<C>Document Revised: January, 1996
<C>Document Revised: June, 1996
<C>Document Revised: March, 2012
|