1.123 class popup

A popup is a menu that is associated with a graphical object, but is normally invisible. When the user depresses a predefined button, the popup is poped-up’. After the user has made a choice, the popup is removed from the display again.

Some types of graphicals have an attribute called dialog_item<->popup. For these types the easiest way to attach a popup to them is to fill this attribute with a popup menu. General graphicals don't have this feature. For these graphicals a popup_gesture object has to be used to connect the popup with some event. See also graphical->popup and graphical->event.

PCE encourages you to associate popup-menus with the right mouse-button only.

By default, a popup menu inverts the current item. This gives odd results on colour displays. You can change this into a box by adding the following line to your Defaults file.

popup.preview_feedback: box

The method popup->execute is activated to execute the behaviour associated with the selected item. The documentation of this method describes the available context parameters.

Forwarding rules for associated messages are described with popup->execute.

User interface:

When (normally) the right button is depressed on an object that has a popup associated to it, the popup will be mapped on the display such that the first option is below the mouse. If possible, the mouse itself is not moved.

The user should HOLD the mouse-button depressed and DRAG to the approprate choice to RELEASE the mouse-button there. This will invoke the associated command.

The user can CANCEL the operation by dragging the mouse-button outside the popup and releasing it.

If an item has a mark _=>_ at the right side, SUB-MENU can be obtained by dragging towards this mark.

Bugs:

Interface styles such as stay-up, OpenWindow like push-pins, etc. are not supported.

See also

- graphical->popup
- class popup_gesture
- class menu_item
- class menu
- class menu_bar
- topic Using menu's
- window-popup
- menu_item-popup
- list_browser-popup
- dialog_item-popup

1.123.1 Instance variables

popup <-> default_item: {first,selection}|any*

Determines the initial positioning of the menu. Values:

• first Position the pointer on the first item with menu_item<-active.
• @nil As first, but places the pointer a few pixels to the left of the item so that it is not immediately selected.
• selection Position the pointer on the current menu<-selection of the popup. In practice this is the last selected item.
• Anything else Position the pointer on the menu item with the specified menu_item<-value.

  See also

menu <- margin: margin=0..

Margin to the left-and-right of the menu for generating the window size. See also menu<-border.

popup <-> update_message: code*

If not @nil, this message is invoked by popup->update. This message is meant to generate the entries of the popup. Activating individual items is normally done by the condition message associated with each menu_item of the popup.

When executed, the following arguments are forwarded:

@receiver	The popup itself
@arg1	The argument of popup->update

Defaults: By default, no updating takes place

See also

- menu_item-condition
- popup->update

1.123.2 Send methods

popup ->close:

Remove the popup from the display. First it will popup->close possible open pullright menus. Then is removes the popup menu from its graphical<-window and adds the window to the pool of window objects used to display popup menu's.

This method is always called as a normal message and thus may be redefined.

popup ->drag: event, check_pullright=[bool]

Handle a drag event. This method is called from popup->event. It should not be used, nor be redefined, except for emergencies.

This method locates the current item using menu<-item_from_event and activates this using menu->preview. If the drag event is on an item with a menu_item<-popup and the event is near the popup marker (see menu<-popup_image), the pullright menu is activated by invoking popup->show_pullright_menu.

popup ->end_group: bool

If this is a pullright menu, set menu_item->end_group in the associated menu_item. This will put a line below the item.

popup ->event: event

Performs the following steps

• If the popup has a -pullright and the event is on an item of this menu, popup->close the pullright menu.
• If the popup has a -pullright and the event is a button-up of the same button that started the popup, assign popup<-selected_item with the pullright menu, assign -pullright with @nil and popup->close the pullright.
• If there is no -pullright and the event is the button-up event, assign popup<-selected_item with menu<-preview and popup->close the popup.
• If the event is a button-down, set popup<-selected_item to @nil and send popup<-button to the event<-button
• If the event is a drag event, update menu->preview. If a pullright area is entered, popup->update the pullright and popup->open it.

popup ->execute: context=[object]*

This method is normally invoked from popup_gesture->terminate. The argument (denoted context) is normally the object to which the popup menu is associated.

First it locates the selected menu_item object and the message to execute. This message is menu_item<-message if this does not yeild @default, otherwise dialog_item<-message. The forwarded arguments are:

• menu<-multiple_selection: @off using menu_item<-message

  @receiver:	The popup
  @arg1:	The context argument

• menu<-multiple_selection: @off using dialog_item<-message

  @receiver:	The popup
  @arg1	menu_item<-value
  @arg2:	The context argument

• menu<-multiple_selection: @on using menu_item<-message

  @receiver:	The popup
  @arg1:	menu_item<-selected
  @arg2:	The context argument

• menu<-multiple_selection: @on using dialog_item<-message

  @receiver:	The popup
  @arg1:	menu_item<-value
  @arg2:	menu_item<-selected
  @arg3:	The context argument

  See also

  popup_gesture->terminate

popup ->initialise: name=[name], message=[code]*

Create a popup menu from its name (which is only displayed if menu<-show_label equals @on) and a message. This message will be executed when a menu_item object is selected that has‘menu_item dialog_item<-message: @default’. Using a message at the popup (menu) level is commonly used if the menu selects from a value-set (fonts, colours, names. ...). If the menu is used to activate commands the actions are normally associated with the individual items.

popup ->open: on=graphical, offset=point, offset_is_pointer=[bool], warp=[bool], ensure_on_display=[bool]

Open a popup menu on the display. Normally invoked from a popup_gesture object. The arguments are:

• on Graphical (window) for which the popup is displayed (popup<-context)
• offset
• offset_is_pointer (default @on) Position of the top-left corner of the popup relative to the popup<-context iff offset_is_pointer equals @off, otherwise the position of the pointer.
• warp_pointer (default @on) If the popup is moved (see ensure_on_display), move the pointer accordingly.
• ensure_on_display (default @on) If @on, move the popup if it would otherwise be (partly) outside the display.

  See also

  popup_gesture->initiate

popup ->reset:

Equivalent to popup->close.

popup ->show_pullright_menu: item=menu_item, event=[event], context=[any]

Show pullright for this item. Called from popup->drag. item is the item for which to show a pullright menu. First updates the menu_item<-popup and -if the popup has menu<-members- opens the popup.

popup ->update: context=any

This behaviour is normally invoked just before the popup-menu is mapped on the display. This is done automatically for popups associated with menu_bars or managed by a popup_gesture (i.e. all normal ways to manage a popup).

Update first invokes popup<->update_message, providing its argument as @arg1. This message is supposed to update the available entries of the popup; not the activation status of the individual entries. Next, popup->update invokes menu->update, which takes care of activating the appropriate entries.

See also

- menu_item-condition
- menu->update
- popup-update_message
- popup_gesture->initiate