POLLING  - v14

polling                       {on|off} {,cc} {,p='<text>'} {,os=<svar>}
{,op1=<pvar>} {,op2=<pvar>}
{,r= l | r | c | h | v | u | <n>}
{,h} {,l} {,foc=<i1>,<i2>} {,wp=<pvar>,<vector>} {,3d}
{,sin=<n_array>} {,timeout=<n>}
data block(s);

Function

Activate the screen cursor enabling the Windowing main loop mechanism to start up. Activating the polling loop means that the user can select one of the widgets present on the screen or pick a point in the graphic area. When events occur VB and SB values are returned. If the primer OFF is defined then the dialogue area disappears. The default is ON.

 

The prompt is activated if a keyboard event is matched by the event handler and the resulting input is stored in <svar>. If a line from a LIST widget is selected during polling, then that line is recorded in <svar>. Utlimately it displays an alpha prompt in a pop up form. The position is defined as relative to popup menu default position (see commands POPUP, POPOSITION).

Parameters

on

Activate polling with the dialogue area visible.

 

 

off

Activate polling pushing down the dialog area.

 

 

cc

Moves the current control to the new point.

 

 

p=

Defines the prompt string for requested keyboard input.

 

 

os=

An output string for keyboard input or LIST line selection.

When using a Treeview control with node UID in the ST system string variable instead of the node’s label. In such case, the label can be extracted from the full node’s path stored in the OS string specified in the POLLING command. The default is “no” and it is compliant to the actual behaviour.
Example:
TREEVIEW_ST_AS_UID=yes
There is a new setting in the INI file, called TREEVIEW_ST_AS_UID, which can be used

 

 

op1=

First output point set to 3D transformed input point.

 

 

op2=

Second output point set to 3D transformed input point.

 

 

r=l

Uses a rubber line effect. Input will be one point.

 

 

r=r

Uses a rubber box effect. Input will be two points.
Colours of a rubberbox expanded either left or right can be set using the COLOUR command in conjunction with the INI/Reg setting RUBBERBOX_COLORS (Update 12.4.0 b01)

 

 

r=c

Uses a rubber circle effect. Input will be two points.

 

 

r=h

Uses a rubber line effect horizontally constrained. Input will be one point.

 

 

r=v

Uses a rubber line effect vertically constrained. Input will be one point.

 

 

r=o

 

A new rubber effect for orthogonal that is the combination of vertical and horizontal constrained. (Update 12.5.1)

 

 

r=u

Uses a rubber unbounded line effect. Input will be two points.

 

 

r=<n>

Constraint the rubber line effect to a direction defined by an angle on the X axis.
 

h

Activates the interactive identify, highlighting the item currently identified by the cursor.
Update 12.4.2 A fragment or fragment range can be excluded from the highlighting process, refer to the HIGHLIGHT command for details.
 

l

Activates the interactive latching, visualising the "latched" point using different shapes of the cursor.
Update from 11.7.0 (b04) to report grid snapping, symbol node point snapping and dimension snapping. Additional cursors are displayed for each of the additional latching criteria - See Notes section below.
 

foc=<i1>,<i2>

It puts the "focus" on the specified button <I2> of the specified panel <i1>.
When using FOC=0,1 in POLLING it is possible to set a tolerance for deciding at what point the mouse movement removes the focus from the Dynamic Input edit field.
A new variable in the INI/Registry configuration called DYNAINPUT_TOLERANCE can be set to the tolerance value which is expressed in pixels. The default is 0, suggested values are in the range [10,20].
 

wp=<pvar>,<vector>

To project the input point onto a plane passing through a point <pvar> and with the normal <vector>.
 

3d

To use a 3D cursor, that is a local axes dependent cursor.
(Update from 11.6.4 b05) The POLLING option 3D, used to display the cursor and the rubber band/box/circle relative to the view (XY plane if WP= not used), has been extended to work also in 2D relative to the local axes, if any.
(Update Note from 11.7.1) The option of 3D circle rubber effect syntax: is as follows
POLLING 3D, R=C, WP=<PVAR>,<VECTOR>, …
implements the new 3D effect.
 

sin=

The name of the array containing the ASCII codes of the keys on the keyboard to be managed as single characters when polling is interrupted by a key press.  Up to 256 hot-keys can be defined.
     It is possible to check the three different cases:

key pressed

shift+key pressed

ctlr+key pressed

Just using the correct codes in the hotkeys SIN-array of the POLLING command; for instance:

117    ;# u

85     ;# shift-u

21     ;# ctrl-u

 

timeout=<n>

The number of milliseconds after which the polling command is automatically terminated even if no mouse button has been pressed Update (11.6.3 B04   See Note below on VB return.
 

data block(s);

The text of the prompt. Each line should be in the form of <message>, with a semi-colon used to terminate the last line.

Examples

polling ;

 

polling ;'pick a point on the screen ...';

 

polling

'pick a point on the screen ...';

 

polling off;

polling cc;

polling op=100,r=l;

polling p='radius ?',os=50;

polling p='coordinates (x,y) ?',os=50

'indicate a point on the screen'

'or type coordinates on the keyboard ...';

polling h;

Notes

vb      values returned :

1             Leftmost mouse button

2             Middle mouse button

3             Rightmost mouse button

0             Keyboard interrupt

5             Accelerator interrupt

6           If timeout stops the command

(Update 11.6.3 B03) Introduced for touchscreen technology to allow starting of polling then moving of the finger off the screen without terminating the operation. The VB is used to check (after POLLING)to see  if the operation was terminated by the user or by a timeout.

8             when a <CR> is hit in the edit controls of the dynamic input panel (see DYNAINPUT command) (Introduced 12.2.0)

9             when patch4034 is set to yes an ONCHANGE command will exit from POLLING.

11           CTRL key plus leftmost mouse button

12           CTRL key plus middle mouse button

13           CTRL key plus rightmost mouse button

14           SHIFT key plus leftmost mouse button

15           SHIFT key plus middle mouse button

16           SHIFT key plus rightmost mouse button

 

sb      values returned :

<space>   Leftmost mouse button

F             Middle mouse button

A             Rightmost mouse button

 

The command always returns five other values :

wt     The type of clicked widget:

1         Drawing Area

2            Notify or Prompt

3            PopupMenu

4            BarMenu

5            Panel

6            List

 

mn   Menu number, if selected

bn   Button number

ln   List number, if selected | Treeview node id

rn   Row number | Index of Combo selection | Treeview child status

 

Combo box - Selection returns in RN, the index of the currently selected item, starting from index=1. When an option is selected from a Combo box as well as the  string value stored in ST, the row number is stored in RN (LN=0 is maintained) (Update v12.4.2)

Treeview - when selecting a treeview node the POLLING command also sets the variables LN and RN. LN contains  the “node id” and RN is “0” if the node has no children, otherwise with children RN is "1". (Update v14.1.1)

 

It returns another value if text button, option menu, toggle button or radio button are pressed

 

st  <str>                                   if text button;

option index                           if option menu;

0 (off) | 1 (on)                       if toggle button;

Option index in a radio box        if radio button.

Node label                              if the treeview and environment variable TREEVIEW_ST_AS_UID=yes

 

The options h and l were mutually exclusive prior to v11.2.1a

 

  Update from 11.7.0 (b03/4) Dynamic SPIN, MAGNIFY and SCROLL are implemented in the POLLING command using meta-keys.  Moving the mouse and holding down the Control, Shift and Control and Shift implements Scroll, Magnify and Spin respectively.

 

Option during POLLING

keyboard

Mouse .

Scroll

CTRL

Middle & Right

Magnify

SHIFT

Left & Middle

Spin

SHIFT-CTRL

Left & Right

 

 Update from 12.3.3  Equally <Shift> and <Ctrl> can be resigned from the dynamic zoom/pan process and instead be parsed as hotkeys during polling.  Note: In order to enable/disable the usage of the <shift> and/or <ctrl> keys for dynamic zoom and pan, the environment variables listed here need to be set:

ZOOM_SHIFT_ENABLED=yes|no

SCROLL_CTRL_ENABLED=yes|no

 

(Update from 12.4.1)Enable/disable the usage of the <shift> and  <ctrl> keys for dynamic spin.  Default is enabled.

SPIN_SHIFT_CTRL_ENABLED=yes|no

 

   Update 11.7.0 (b04)Further cursor options introduced for use with POLLING L and are accessible from the SHAPE command. The value of these cursors is that some intelligence may be built into the cursoring system.  The correspondence between the value passed to the SHAPE command with the CUR primer and the image of the cursor is described in the following figure.

IDC_APPSTARTING

IDC_ARROW

IDC_IBEAM

IDC_IBEAM         

2001

5      2002       

6      2004

7      IDC_SIZENESW

8      IDC_SIZENS

9      IDC_SIZENWSE

10     2005

11     2003

12     IDC_WAIT

13     IDC_ICON

14     IDC_SIZE

15     IDC_NO

16     IDC_SIZEWE

17     IDC_UPARROW

18     not used

19     not used

20     2006

21     2007

22     2008

23     not used

…

63     not used

 

The numbers like 2000, 2001, etc. correspond to entries in the Eagle resource file and the correspondent shape are :

2001        

2002        

2003        

2004        

2005        

2006        

2007        

2008        

2015           

 

  Update v11.9-v12. Information about which TAB has been selected may now be retrieved from the POLLING output. This also means that tab selection now interrupts the polling loop.

 

  Update v12.1.0 Pressing escape terminates polling with VB=1 with the mouse pointing to gwind or panels or lists or barmenu or anything else.

 

  Update v12.3 It is possible to use CTRL-<digit> (the control key together with a number key) during the POLLING command (e.g: CTRL 5), which returns the digit in the output string, like the accelerators (SIN=) and a different VB value, which is 7 by default or can be defined in the INI file with the variable DIGITHOTKEYSVB

 

  Update v12.3 Focus-in / focus-out can terminate polling has an environment variable workaround required to implement this behavior.  Setting the environment variable PATCH4084 to “yes” activates the action.

 

  Update v12.3.0b07 COMMAND - when the command line gets the focus and a RET is typed POLLING must exit with WT=12,VB=0 and ST='' (null)

 

Update v12.3.3b01 POLLING also handles DEL,BSP,INS,HOME, and other keys with hotkeys.

 

See Also

cursor, scursor, set, highlight, Configuring Eagle, click, treeview