The Python X Library - Display

Go to the first, previous, next, last section, table of contents.

## Display

Display information retrieval methods:

Method: Display get_display_name ( )

  Returns the name used to connect to the server, either provided when creating the `Display` object, or fetched from the environmental variable `$DISPLAY`.

Method: Display fileno ( )

  Returns the file descriptor number of the underlying socket. This method is provided to allow `Display` objects to be passed `select.select()`.

Method: Display close ( )

  Close the display, freeing the resources that it holds.

Method: Display set_error_handler ( handler )

  Set the default error handler which will be called for all unhandled errors. handler should take two arguments as a normal request error handler, but the second argument (the request) will be None.

  See section Error Handling.

Method: Display flush ( )

  Flush the request queue, building and sending the queued requests. This can be necessary in applications that never wait for events, and in threaded applications.

Method: Display sync ( )

  Flush the queue and wait until the server has processed all the queued requests. Use this e.g. when it is important that errors caused by a certain request is trapped.

Method: Display next_event ( )

  Return the next event. If there are no events queued, it will block until the next event is fetched from the server.

Method: Display pending_events ( )

  Return the number of events queued, i.e. the number of times that `Display.next_event()` can be called without blocking.

Method: Display has_extension ( extension )

  Check if both the server and the client library support the X extension named extension.

Method: Display create_resource_object ( type, id )

  Create a resource object of type for the integer id. type should be one of the following strings:

  `resource`
  `drawable`
  `window`
  `pixmap`
  `fontable`
  `font`
  `gc`
  `colormap`
  `cursor`

  This function can be used when a resource ID has been fetched e.g. from an resource or a command line argument. Resource objects should never be created by instantiating the appropriate class directly, since any X extensions dynamically added by the library will not be available.

Method: Display screen ( sno = None )

  Return the information about screen number sno, or the default screen if sno is `None`.

  The return object has the following attributes:

  `root`
    The screen root window.
  `default_colormap`
    The default colormap for the root window and its children.
  `white_pixel`
  `black_pixel`
    The pixel values for white and black, respectively, in the default colormap.
  `current_input_mask`
    The event mask of the root window at the time the connection was set up.
  `width_in_pixels`
  `height_in_pixels`
    The size of the root window in pixels, i.e. the size of the entire screen.
  `width_in_mms`
  `height_in_mms`
    The physical size of the screen, in millimeters.
  `min_installed_maps`
  `max_installed_maps`
    The minimum and maximum number of colormaps that can be installed at the same time.
  `root_visual`
    The visual type of the root window.
  `backing_store`
    Whether the screen supports backing store, one of the values `X.WhenMapped`, `X.NotUseful`, or `X.Always`.
  `save_unders`
    True if the screen supports save unders.
  `root_depth`
    The depth of the root window.
  `allowed_depths`
    A list of the pixmap and windows depths that this screen supports. The list items have the following attributes:
    `depth`
      This depth is supported by the screen.
    `visuals`
      A list of visual types that is valid for this depth. If this list is empty, this depth is only valid for pixmaps and not for windows. The list items have the following attributes:
      `visual_id`
        The ID of this visual.
      `visual_class`
        One of `X.StaticGrey`, `X.StaticColor`, `X.TrueColor`, `X.GrayScale`, `X.PseudoColor`, or `X.DirectColor`.
      `bits_per_rgb_value`
        The number of bits used to represent an entire RGB-value, allowing a total of `2^bits_per_rgb_value` distinct colors.
      `colormap_entries`
        The number of free entries in a newly created colormap.
      `red_mask`
      `blue_mask`
      `green_mask`
        Bitmasks selecting the three color components from the entire RGB value.

Method: Display screen_count ( )

  Return the total number of screens on the display.

Method: Display get_default_screen ( )

  Return the number of the default screen, extracted from the display name.

Method: Display keycode_to_keysym ( keycode, index )

  Convert a keycode to a keysym, looking in entry index. Normally index 0 is unshifted, 1 is shifted, 2 is alt grid, and 3 is shift+alt grid. If that key entry is not bound, `X.NoSymbol` is returned.

Method: Display keysym_to_keycode ( keysym )

  Look up the primary keycode that is bound to keysym. If several keycodes are found, the one with the lowest index and lowest code is returned. If keysym is not bound to any key, 0 is returned.

Method: Display keysym_to_keycodes ( keysym )

  Look up all the keycodes that is bound to `keysym`. A list of tuples `(keycode, index)` is returned, sorted primarily on the lowest index and secondarily on the lowest keycode.

Method: Display refresh_keyboard_mapping ( evt )

  This method should be called once when a `MappingNotify` event is received, to update the keymap cache. evt should be the event object.

Method: Display lookup_string ( keysym )

  Attempt to convert keysym into a single character or a string. If no translation is found, `None` is returned.

Method: Display rebind_string ( keysym, newstring )

  Set the string representation of `keysym` to `newstring`, so that it will be returned by `Display.lookup_string()`.

X requests methods:

Method: Display intern_atom ( name, only_if_exists = 0 )

  Intern the string name, returning its atom number. If only_if_exists is true and the atom does not already exist, it will not be created and `X.NONE` is returned.

Method: Display get_atom_name ( atom )

  Look up the name of atom, returning it as a string. Will raise `BadAtom` if atom does not exist.

Method: Display get_selection_owner ( selection )

  Return the window that owns selection (an atom), or `X.NONE` if there is no owner for the selection. Can raise `BadAtom`.

Method: Display send_event ( destination, event, event_mask = 0, propagate = 0, onerror = None )

  Send a synthetic event to the window `destination` which can be a window object, or `X.PointerWindow` or `X.InputFocus`. `event` is the event object to send, instantiated from one of the classes in `protocol.events`. See XSendEvent(3X11) for details.

  There is also a `Window.send_event()` method.

Method: Display ungrab_pointer ( time, onerror = None )

  Release a grabbed pointer and any queued events. See XUngrabPointer(3X11).

Method: Display change_active_pointer_grab ( event_mask, cursor, time, onerror = None )

  Change the dynamic parameters of a pointer grab. See XChangeActivePointerGrab(3X11).

Method: Display ungrab_keyboard ( time, onerror = None )

  Ungrab a grabbed keyboard and any queued events. See XUngrabKeyboard(3X11).

Method: Display allow_events ( mode, time, onerror = None )

  Release some queued events. mode should be one of `X.AsyncPointer`, `X.SyncPointer`, `X.AsyncKeyboard`, `X.SyncKeyboard`, `X.ReplayPointer`, `X.ReplayKeyboard`, `X.AsyncBoth`, or `X.SyncBoth`. time should be a timestamp or `X.CurrentTime`.

Method: Display grab_server ( onerror = None )

  Disable processing of requests on all other client connections until the server is ungrabbed. Server grabbing should be avoided as much as possible.

Method: Display ungrab_server ( onerror = None )

  Release the server if it was previously grabbed by this client.

Method: Display warp_pointer ( x, y, src_window = X.NONE, src_x = 0, src_y = 0, src_width = 0, src_height = 0, onerror = None )

  Move the pointer relative its current position by the offsets (x, y). However, if src_window is a window the pointer is only moved if the specified rectangle in src_window contains it. If src_width is 0 it will be replaced with the width of src_window - src_x. src_height is treated in a similar way.

  To move the pointer to absolute coordinates, use `Window.warp_pointer()`.

Method: Display set_input_focus ( focus, revert_to, time, onerror = None )

  Set input focus to focus, which should be a window, `X.PointerRoot` or `X.NONE`. revert_to specifies where the focus reverts to if the focused window becomes not visible, and should be `X.RevertToParent`, `RevertToPointerRoot`, or `RevertToNone`. See XSetInputFocus(3X11) for details.

  There is also a `Window.set_input_focus()`.

Method: Display get_input_focus ( )

  Return an object with the following attributes:

  `focus`
    The window which currently holds the input focus, `X.NONE` or `X.PointerRoot`.
  `revert_to`
    Where the focus will revert, one of `X.RevertToParent`, `RevertToPointerRoot`, or `RevertToNone`.

Method: Display query_keymap ( )

  Return a bit vector for the logical state of the keyboard, where each bit set to 1 indicates that the corresponding key is currently pressed down. The vector is represented as a list of 32 integers. List item N contains the bits for keys 8N to 8N + 7 with the least significant bit in the byte representing key 8N.

Method: Display open_font ( name )

  Open the font identifed by the pattern name and return its font object. If name does not match any font, `None` is returned.

Method: Display list_fonts ( pattern, max_names )

  Return a list of font names matching pattern. No more than max_names will be returned.

Method: Display list_fonts_with_info ( pattern, max_names )

  Return a list of fonts matching pattern. No more than max_names will be returned. Each list item represents one font and has the following properties:

  `name`
    The name of the font.
  `min_bounds`
  `max_bounds`
  `min_char_or_byte2`
  `max_char_or_byte2`
  `default_char`
  `draw_direction`
  `min_byte1`
  `max_byte1`
  `all_chars_exist`
  `font_ascent`
  `font_descent`
  `replies_hint`
    See the descripton of XFontStruct in XGetFontProperty(3X11) for details on these values.
  `properties`
    A list of properties. Each entry has two attributes:
    `name`
      The atom identifying this property.
    `value`
      A 32-bit unsigned value.

Method: Display set_font_path ( path, onerror = None )

  Set the font path to path, which should be a list of strings. If path is empty, the default font path of the server will be restored.

Method: Display get_font_path ( )

  Return the current font path as a list of strings.

Method: Display query_extension ( name )

  Ask the server if it supports the extension name. If it is supported an object with the following attributes is returned:

  `major_opcode`
    The major opcode that the requests of this extension uses.
  `first_event`
    The base event code if the extension have additional events, or 0.
  `first_error`
    The base error code if the extension have additional errors, or 0.

  If the extension is not supported, `None` is returned.

Method: Display list_extensions ( )

  Return a list of all the extensions provided by the server.

Method: Display change_keyboard_mapping ( first_keycode, keysyms, onerror = None )

  Modify the keyboard mapping, starting with first_keycode. keysyms is a list of tuples of keysyms. `keysyms[n][i]` will be assigned to keycode `first_keycode+n` at index `i`.

Method: Display get_keyboard_mapping ( first_keycode, count )

  Return the current keyboard mapping as a list of tuples, starting at first_keycount and no more than count.

Method: Display change_keyboard_control ( onerror = None, **keys )

  Change the parameters provided as keyword arguments:

  `key_click_percent`
    The volume of key clicks between 0 (off) and 100 (load). -1 will restore default setting.
  `bell_percent`
    The base volume of the bell, coded as above.
  `bell_pitch`
    The pitch of the bell in Hz, -1 restores the default.
  `bell_duration`
    The duration of the bell in milliseconds, -1 restores the default.
  `led`
  `led_mode`
    `led_mode` should be `X.LedModeOff` or `X.LedModeOn`. If `led` is provided, it should be a 32-bit mask listing the LEDs that should change. If `led` is not provided, all LEDs are changed.
  `key`
  `auto_repeat_mode`
    `auto_repeat_mode` should be one of `X.AutoRepeatModeOff`, `X.AutoRepeatModeOn`, or `X.AutoRepeatModeDefault`. If `key` is provided, that key will be modified, otherwise the global state for the entire keyboard will be modified.

Method: Display get_keyboard_control ( )

  Return an object with the following attributes:

  `global_auto_repeat`
    `X.AutoRepeatModeOn` or `X.AutoRepeatModeOff`.
  `auto_repeats`
    A list of 32 integers. List item N contains the bits for keys 8N to 8N + 7 with the least significant bit in the byte representing key 8N. If a bit is on, autorepeat is enabled for the corresponding key.
  `led_mask`
    A 32-bit mask indicating which LEDs are on.
  `key_click_percent`
    The volume of key click, from 0 to 100.
  `bell_percent`
  `bell_pitch`
  `bell_duration`
    The volume, pitch and duration of the bell.

Method: Display bell ( percent = 0, onerror = None )

  Ring the bell at the volume percent which is relative the base volume. See XBell(3X11).

Method: Display change_pointer_control ( accel = None, threshold = None, onerror = None )

  To change the pointer acceleration, set accel to a tuple `(num, denum)`. The pointer will then move `num/denum` times the normal speed if it moves beyond the threshold number of pixels at once. To change the threshold, set it to the number of pixels. -1 restores the default.

Method: Display get_pointer_control ( )

  Return an object with the following attributes:

  `accel_num`
  `accel_denom`
    The acceleration as numerator/denumerator.
  `threshold`
    The number of pixels the pointer must move before the acceleration kicks in.

Method: Display set_screen_saver ( timeout, interval, prefer_blank, allow_exposures, onerror = None )

  See XSetScreenSaver(3X11).

Method: Display get_screen_saver ( )

  Return an object with the attributes `timeout`, `interval`, `prefer_blanking`, `allow_exposures`. See XGetScreenSaver(3X11) for details.

Method: Display change_hosts ( mode, host_family, host, onerror = None )

  mode is either `X.HostInsert` or `X.HostDelete`. host_family is one of `X.FamilyInternet`, `X.FamilyDECnet` or `X.FamilyChaos`.

  host is a list of bytes. For the Internet family, it should be the four bytes of an IPv4 address.

Method: Display list_hosts ( )

  Return an object with the following attributes:

  `mode`
    `X.EnableAccess` if the access control list is used, `X.DisableAccess` otherwise.
  `hosts`
    The hosts on the access list. Each entry has the following attributes:
    `family`
      `X.FamilyInternet`, `X.FamilyDECnet`, or `X.FamilyChaos`.
    `name`
      A list of byte values, the coding depends on `family`. For the Internet family, it is the 4 bytes of an IPv4 address.

Method: Display set_access_control ( mode, onerror = None )

  Enable use of access control lists at connection setup if mode is `X.EnableAccess`, disable if it is `X.DisableAccess`.

Method: Display set_close_down_mode ( mode, onerror = None )

  Control what will happen with the client's resources at connection close. The default is `X.DestroyAll`, the other values are `X.RetainPermanent` and `X.RetainTemporary`.

Method: Display force_screen_saver ( mode, onerror = None )

  If mode is `X.ScreenSaverActive` the screen saver is activated. If it is `X.ScreenSaverReset`, the screen saver is deactivated as if device input had been received.

Method: Display set_pointer_mapping ( map )

  Set the mapping of the pointer buttons. map is a list of logical button numbers. map must be of the same length as the list returned by `Display.get_pointer_mapping()`.

  `map[n]` sets the logical number for the physical button `n+1`. Logical number 0 disables the button. Two physical buttons cannot be mapped to the same logical number.

  If one of the buttons to be altered are logically in the down state, `X.MappingBusy` is returned and the mapping is not changed. Otherwise the mapping is changed and `X.MappingSuccess` is returned.

Method: Display get_pointer_mapping ( )

  Return a list of the pointer button mappings. Entry N in the list sets the logical button number for the physical button N+1.

Method: Display set_modifier_mapping ( keycodes )

  Set the keycodes for the eight modifiers `X.Shift`, `X.Lock`, `X.Control`, `X.Mod1`, `X.Mod2`, `X.Mod3`, `X.Mod4` and `X.Mod5`. keycodes should be a eight-element list where each entry is a list of the keycodes that should be bound to that modifier.

  If any changed key is logically in the down state, `X.MappingBusy` is returned and the mapping is not changed. If the mapping violates some server restriction, `X.MappingFailed` is returned. Otherwise the mapping is changed and `X.MappingSuccess` is returned.

Method: Display get_modifier_mapping ( )

  Return a list of eight lists, one for each modifier. The list can be indexed using `X.ShiftMapIndex`, `X.Mod1MapIndex`, and so on. The sublists list the keycodes bound to that modifier.

Method: Display no_operation ( onerror = None )

  Do nothing but send a request to the server.

Go to the first, previous, next, last section, table of contents.