Andrew Branscom: /* 5 Constant reference */

2025-04-29T01:23:51Z

5 Constant reference

← Older revision		Revision as of 21:23, 28 April 2025
Line 296:		Line 296:
	(define KEYPAD_SPECIAL_CANCEL 3)		(define KEYPAD_SPECIAL_CANCEL 3)

			==<br /> References ==

			<references />

			==<br /> Related Links ==

			*


	[[Category:Keyboard]]		[[Category:Keyboard]]
			[[Category:SCI Keyboard]]
	[[Category:Classes]]		[[Category:Classes]]
			[[Category:SCI Classes]]
	[[Category:I/O]]		[[Category:I/O]]
			[[Category:SCI I/O]]
	[[Category:Examples]]		[[Category:Examples]]
	[[Category:SCI Examples]]		[[Category:SCI Examples]]

Andrew Branscom: 1 revision imported

2025-04-02T22:22:04Z

1 revision imported

← Older revision	Revision as of 18:22, 2 April 2025
(No difference)

Andrew Branscom: Andrew Branscom moved page Generic Keypad class to Generic Keypad Class without leaving a redirect

2025-04-02T21:30:55Z

Andrew Branscom moved page Generic Keypad class to Generic Keypad Class without leaving a redirect

New page

[[Category:SCI Pages]]
[[Category:Temp SCI Import Pages]]
[[Category:Temp SCI Tutorials]]
[[SCI Tutorials]]
[[SCI Tutorials and Guides]]

<div align="center"><span style="font-size: 22pt">Generic Keypad Class</span><br />
'''By Lars Skovlund'''</div>

<br />
==<br /> Introduction ==

Note that I use the ego view for buttons (as I said, I am not a graphic artist). The first the buttons from the left are number buttons, and add the numbers 1, 2 and 3 to the keypad text. The next button cancels, the one after that is backspace, and the last one OK. It would be great if someone would help me make better graphics for the demo code. Instructions are in the documentation. You will also need to add the word 'keypad' to your vocabulary.

Code in the attached file, along with documentation.

[http://sierrahelp.com/download.php?file=Files/SCI/GenericKeypadClass.zip Generic Keypad Class Files]

Lars

The Keypad SCI class<br />
Lars Skovlund<br />
January 17, 2007<br />
 

==1 Introduction==

This is the documentation for the Keypad SCI class, written by Lars Skovlund. I have attempted to make the class as general as possible. Therefore, the class and its descendant DisplayKeypad support arbitrarily long strings of any kind, so it is possible, for instance, to have each button represent a word so the user can construct sentences. The DisplayKeypad class prints the input string somewhere on the screen via the Display kernel call (all parameters are selectable via properties).

The following is a complete feature list for the keypad:

* No keyboard input, for generality reasons.
* Special button functionality, such as enter, backspace and cancel.
* Optionally invokes a script when initially showing the keypad and when the enter button is pressed.
* Optional auto exit mode in which the keypad triggers as soon as the input string reaches its maximum length, as if the user explicitly pressed the enter button.
* Can require a specific number of buttons to be pressed, or accept any number of button presses.
* Can play a sound when a button is pressed.
* Optional text display (DisplayKeypad).
* A background view can be used or not.

==2 Example of use==

===2.1 Declarations===

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(local kptxt[5])

(instance myKeyPad of DisplayKeypad
(properties
maxLength 4
autoExit FALSE
script 0
longestText 1 /* one character */
color clBLACK
back clWHITE
x 20
y 160
requireMax TRUE
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key1 of KeypadButton
(properties
x 100
y 100
view 0
loop 0
text "1"
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key2 of KeypadButton
(properties
x 120
y 100
view 0
loop 2
text "2"
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key3 of KeypadButton
(properties
x 140
y 100
view 0
loop 1
text "3"
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key4 of KeypadButton
(properties
x 160
y 100
view 0
loop 5
special KEYPAD_SPECIAL_CANCEL
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key5 of KeypadButton
(properties
x 180
y 100
view 0
loop 6
special KEYPAD_SPECIAL_BKSP
)
)</syntaxhighlight>

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance key6 of KeypadButton
(properties
x 200
y 100
view 0
loop 3
special KEYPAD_SPECIAL_ENTER
)
)</syntaxhighlight>

===2.2 Handling the enter and cancel buttons===

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(instance KeypadScript of Script
(properties)
(method (changeState newState)
(super:changeState(newState))
(switch (newState)
(case KEYPAD_DONE_STATE
((send client:hide(FALSE))
FormatPrint("You typed: %s" @kptxt)))
(case KEYPAD_ERROR_STATE
(FormatPrint("You need to press %d buttons."
(send client:maxLength()))))
)
)
)</syntaxhighlight>

===2.3 Initialization and activation===

<div class="CodeBlockHeader">Code:</div>
<syntaxhighlight lang="sci">(myKeyPad:setScript(KeypadScript) outputString(@kptxt)
init(key1 key2 key3 key4 key5 key6))

(myKeyPad:init() show()) /* The init ensures that the keypad can
be used any number of times. */</syntaxhighlight>

==3 What to draw==

You will need a view consisting of several loops, one for each button. Each loop should contain two cels: The button in its normal and depressed state, respectively. It is important that the cels are ordered in this way; the code depends on it, and you should not set the cel property to anything when declaring KeypadButtons.

If you want a background view you can draw this as a separate loop. Declare it in your code as an instance of the Prop class. Then refer to it in your Keypad instance using the backView property.

==4 Class reference==

===4.1 Keypad class===

'''Superclass: EventHandler'''

This class provides the base functionality for keypads.

====''Methods of the Keypad class:''====

'''(Keypad init: buttons . . . )'''

This function initializes the object, as is the case with every SCI class. In particular, it resets the input string and notifies the controlling script. Buttons is a list of button views (instances of KeypadButton) to include in the keypad.

'''(Keypad show:)'''

Displays the keypad. The player is prevented from moving until the keypad is dismissed.

'''(Keypad hide: doCue)'''

Hides the keypad. DoCue should be set to TRUE if the “enter” button was pressed, FALSE otherwise. When the script is called, the buttons have not yet been removed from the screen. If you want this, your script must explicitly call hide with a FALSE parameter (to avoid infinite recursion)—this is what the example code does, see section 2.2.

'''(Keypad backspace:)'''

Self-explanatory. You will need to override this if you use text of varying lengths for the buttons.

'''(Keypad draw:)'''

'''(Keypad setSize:)'''

Do nothing. They are only here to prevent the game from crashing in certain situations (in particular, restoring the game to a position where the keypad is displayed).

'''(Keypad depress: which)'''

Simulates the pressing of a button. Which refers to an actual instance of KeypadButton.

'''(Keypad setScript: newScript params)'''

Sets the controlling script of the keypad. This script is called once when the keypad is initially displayed and once when the user presses “enter”. It is not called if the user cancels the dialog.

====''Properties of the Keypad class:''====

'''outputString''' Points to the output buffer. Remember to set this at run time, and remember that it must be big enough for anything the player might press. Use a local variable, as shown in section 2.1.

'''maxLength''' Indicates the length of the output buffer.

'''autoExit''' Boolean variable which toggles the “auto exit” mode, described in the introduction.

'''backView''' Points to an instance of Prop which is displayed when the keypad is activated. It is meant to be used for a background, hence the name.

'''backPri''' Indicates the priority of the background. May be omitted; the priority of the buttons is always 1 greater than this value, if specified.

'''btnSound''' Points to an instance of Sound which is played whenever the user presses a button.

'''longestText''' Indicates the length of the longest button text.

'''script''' Indicates the controlling script. Use setScript to set this, never set it directly.

'''state''' Boolean variable. Indicates whether the keypad is currently shown or not.

'''special''' Not used for anything. Works around a chicken-and-egg problem regarding selector names in SCI Studio.

'''requireMax''' Setting this to true makes the keypad require maxLength characters to be filled in. If this requirement is not met when the player presses enter, the attached script executes its keypad error state. You can do whatever you want here, including doing nothing, displaying an error message, or blowing up the universe. The keypad remains functional after the script returns.

;Notes

For the predefined script, three states are predefined. Constants are provided
in the enclosed header file.

===4.2 KeypadButton class===

'''Superclass: Prop'''

This class provides the button views to be used for the keypad; they provide an event handler and a special feed-back interface for the <u>Keypad</u> class. None of the overridden methods are meant to be called directly.

'''''Methods of the KeypadButton class:'''''

'''(KeypadButton init: theClient priority)'''

'''(KeypadButton handleEvent: event)'''

'''''Properties of the KeypadButton class:'''''

'''text''' The text to add when the button is pressed.

'''special''' The special meaning that this button is to have.

'''client''' A pointer to the keypad which “owns” this button. Filled in automatically.

;Notes

Three special button types are provided beside the default, namely enter, backspace and cancel.

===4.3 DisplayKeypad class===

'''Superclass: Keypad'''

This class provides the additional functionality of displaying the current text string at a predetermined position on the screen. All of the listed properties have the same format as those passed to the Display kernel function.

'''''Properties of the DisplayKeypad class:'''''

'''underBits''' stores a handle to the screen area under the text string.

'''x'''

'''y''' Coordinates where the text string is to be displayed.

'''font''' The font to use.

'''color''' The foreground color.

'''back''' The background color.

'''width''' The width to use for wrapping the text, if that should ever be necessary.

'''align''' The alignment to use.

==5 Constant reference==

(define KEYPAD_INIT_STATE 0)<br />
(define KEYPAD_DONE_STATE 1)<br />
(define KEYPAD_ERROR_STATE 2)

(define KEYPAD_SPECIAL_NONE 0)<br />
(define KEYPAD_SPECIAL_ENTER 1)<br />
(define KEYPAD_SPECIAL_BKSP 2)<br />
(define KEYPAD_SPECIAL_CANCEL 3)

 

[[Category:Keyboard]]
[[Category:Classes]]
[[Category:I/O]]
[[Category:Examples]]
[[Category:SCI Examples]]

Generic Keypad Class - Revision history

Andrew Branscom: /* 5 Constant reference */

Andrew Branscom: 1 revision imported

Andrew Branscom: Andrew Branscom moved page Generic Keypad class to Generic Keypad Class without leaving a redirect