Component: Keypad (Generic) (Inputs: Keypads)

Author	Matrix Ltd
Version	1.5 (Development)
Category	Inputs: Keypads

Keypad (Generic) component

Generic component to create a raster scanned custom keypad or button matrix. By default, each key is labelled with its ASCII return character. Alternatively, each key may use an image as a label. To use a custom key shape, build a single key, then point to it with the 'Custom key shape" property. If the custom shape is a group, any item within the group that has a handle beginning with "label" will have the key label/image applied to it automatically.

This component can be used as a base to create child components

The following components all inherit the traits of Keypad (Generic):

-

Keypad (Cursor 3x3)	A preset keypad component with up, down, left and right cursors, and a selection of function keys, in a 3 by 3 matrix. Return values (Index or Number) are... 0 = F1, 1 = Up, 2 = F3 3 = left, 4 = OK, 5 = right 6 = F2, 7 = down, 8 = F4. 255 = No key pressed.
Keypad (EB014 3x4)	Preset keypad based around the 3 * 4 unit, as used by the Matrix EB014 E-block
Keypad (Hex 4x4)	Preset keypad for entering hexadecimal numbers. Macros 'GetIndex' or 'GetNumber' will return the decimal equivalent of the number pressed, or 255 when no key is pressed. 'GetString' will return the character, including 'ABCDEF'.

Examples

3 x 4 Keypad Schematic

Example schematic of a 3 x 4 Keypad.

Keypad Based Door Entry System

Each key press on the keypad is fed into the Circular Buffer component. We then poll the buffer to see if the correct characters for the password have been entered. Keypad Door Entry If the correct sequence is detected then we activate the solenoid component for 5 seconds.

Downloadable macro reference

WaitPressed

Blocking call that waits for one of the keys on the keypad to be pressed. The index of the key that was pressed is passed back to the user.

Parameters

This macro has no parameters

Return value

BYTE : Index of the first key pressed.

GetAscii

Gets the ASCII value for the current keypress. If no key is pressed then the macro returns the value 255.

Parameters

This macro has no parameters

Return value

BYTE : ASCII code of the pressed switch (or 255 if none pressed)

GetString

Gets the ASCII value for the current keypress and returns in the form of a string. If no key pressed then the macro returns the value 255.

Parameters

This macro has no parameters

Return value

STRING : Single character representing the pressed key, or an empty string if none pressed.

GetNumber

Gets the numeric value for the current keypress. If no key pressed then the macro returns the value 255.

Parameters

This macro has no parameters

Return value

BYTE : Number return value of the pressed key, or 255 if none pressed.

GetIndex

Gets the index value for the current keypress. If no key pressed then the macro returns the value 255.

Parameters

This macro has no parameters

Return value

BYTE : Index of the pressed switch, or 255 if none pressed.

WaitReleased

Blocking call that waits for the keys on the keypad to be released. If no key is pressed then the function will return immediatley.

Parameters

This macro has no parameters

Return value

This call does not return a value

Simulation macro reference

This component does not contain any simulation macros

Property reference

Columns

This property is of type Signed integer and can be referenced with the variable name num_columns.

Number of columns (left to right) in the array of keys.

Must be a value from one to four.

Column spacing

This property is of type Floating point and can be referenced with the variable name column_space.

Distance between columns in current world units.

Rows

This property is of type Signed integer and can be referenced with the variable name num_rows.

Number of rows (top to bottom) in the key matrix.

Must be a value from one to four.

Row spacing

This property is of type Floating point and can be referenced with the variable name row_space.

Distance between rows in current world units.

First row

This property is of type Fixed list of ints and can be referenced with the variable name key_align.

Decide whether rows are counted from the top to the bottom (default), or from the bottom to the top.

Key movement

This property is of type Floating point and can be referenced with the variable name key_movement.

The distance that the keys move into the panel when pressed.

ASCII

This property is of type Line of text and can be referenced with the variable name ascii_returns.

A list of return values for the 'GetString' and 'GetASCII' macros. Enter a string with one character

per key, in order of key scanning.

Columns are counted first (left-to-right), then rows (direction set by the 'First Row' property)

e.g. for a 2*2 grid, the order would be...

[Row0, Column0], [Row0,Column1], ][Row1, Column0], [Row1, Column1]

Numbers

This property is of type Multiple lines of text and can be referenced with the variable name intfixed.

A list of return values for the 'GetNumber' macro. Enter a comma separated list with one integer value

per key, in order of key scanning.

Columns are counted first (left-to-right), then rows (direction set by the 'First Row' property)

e.g. for a 2*2 grid, the order would be...

[Row0, Column0], [Row0,Column1], ][Row1, Column0], [Row1, Column1]

Column 1

This property is of type Single digital pin and can be referenced with the variable name pin_col1.

Pin for the first column of keys.

Columns are counted from left to right.

Column 2

This property is of type Single digital pin and can be referenced with the variable name pin_col2.

Pin for the second column of keys.

Columns are counted from left to right.

Column 3

This property is of type Single digital pin and can be referenced with the variable name pin_col3.

Pin for the third column of keys.

Columns are counted from left to right.

Row 1

This property is of type Single digital pin and can be referenced with the variable name pin_row1.

Pin for the first row of keys.

Columns are counted from top to bottom by default - they can be counted from bottom to top

by changing the 'First Row' property in the 'Dimensions' section.

Row 2

This property is of type Single digital pin and can be referenced with the variable name pin_row2.

Pin for the second row of keys.

Columns are counted from top to bottom by default - they can be counted from bottom to top

by changing the 'First Row' property in the 'Dimensions' section.

Row 3

This property is of type Single digital pin and can be referenced with the variable name pin_row3.

Pin for the third row of keys.

Columns are counted from top to bottom by default - they can be counted from bottom to top

by changing the 'First Row' property in the 'Dimensions' section.

Row 4

This property is of type Single digital pin and can be referenced with the variable name pin_row4.

Pin for the fourth row of keys.

Columns are counted from top to bottom by default - they can be counted from bottom to top

by changing the 'First Row' property in the 'Dimensions' section.

Custom key shape

This property is of type Panel object and can be referenced with the variable name target_handle.

To use a custom shape for the keys...

1 - On the System Panel, use shapes and/or meshes to design a new key shape. The top surface of the key, where your finger would press, must be uppermost in the Z-axis.

2 - If your key requires a label, include an iobject suitable for drawing a lable onto, and give it a handle name beginning with the word 'label'.

3 - The new key design can be made up of many individual objects - make sure to select them all and group them toegether into a single item.

4 - Now set the 'Cusrtom' property to point at your new design. The original 'prototype' will be hidden, and duplicated into the keypad matrix as many times as required. If there is a 'label' object inside the key design, each key's 'ASCII' return value will be printed there.

5 - Use the 'Button' properties below to set colours, and optional bitmap labels, for individual keys.

Label font

This property is of type Font picker and can be referenced with the variable name label_font.

Set the font here to use for printing the 'ASCII' labels to the inidividual key-caps.

Key color

This property is of type Color picker and can be referenced with the variable name key_color1.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color1.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image1.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color2.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label Color

This property is of type Color picker and can be referenced with the variable name label_color2.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image2.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color3.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color3.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image3.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color4.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color4.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image4.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color5.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color5.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image5.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color6.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker with transparency and can be referenced with the variable name label_color6.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image6.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color7.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color7.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image7.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color8.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker with transparency and can be referenced with the variable name label_color8.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image8.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color9.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color9.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image9.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color10.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color10.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

image

This property is of type Filename and can be referenced with the variable name image10.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color11.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color11.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image11.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color12.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color12.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image12.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color13.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color13.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image13.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color14.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color14.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image14.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color15.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color15.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image15.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.

Key color

This property is of type Color picker and can be referenced with the variable name key_color16.

Set the color of the key body here. This is applied to all objects making up a key, including the

background color of any text labels.

Label color

This property is of type Color picker and can be referenced with the variable name label_color16.

Set the color for the default 'ASCII' text label on the key-cap. This setting will be ignored if a

bitmap is set for the key label.

Image

This property is of type Filename and can be referenced with the variable name image16.

Choose a bitmap file (.bmp, .jpg, .png) to use instead of the default 'ASCII' key legend.

The bitmap will be drawn onto any object within the key component with a handle that begins

with the word 'label'.