User API idea

  1. User API idea
    1. Introduction
    2. Concept
    3. Facility API
      1. Input
      2. Window management
      3. Undo
      4. Naming
      5. Property group
    4. Extension API
      1. Focus
      2. Geometry
      3. Layout manager
      4. Layer
      5. Group management
      6. Frame management
      7. Hide
      8. Window shadow
      9. Shortcut
      10. Selection
      11. Current frame
      12. Zoom
      13. Discussion

Introduction

Here is some thought about an API for the users of CLFSWM, because CLFSWM is meant to be a programmable window manager. This could be a categorized list of feature that CLFSWM could provide. This API should not be tied to a particular implementation.

Comment:

Concept

  • window: application window (X window).
  • frame: A set of frame that are geometrically contained.
    • The identity of a frame is the path in the geometry inclusion tree (frame tree)
    • A frame has a list of its children (frame-children) which are frames
    • A frame has only one parent
    • Special frame:
      • A window which is its own frame.
      • The root frame which parent is itself
  • group: An arbitrary set of group.
    • A group has a name that is unique among the membership
    • The identity of a group is the path in the DAG. A group can have multiple identity.
    • A group has a list of member (group-member) which are groups
    • A group cannot contain itself (transitive)
    • A group can be a member of different group but at least one.
    • Special group
      • A frame which is its own group. The group-member have at least the member of the frame-children.
      • The root group is a member of no group and is named "*root*"
  • operation:
    • name
    • parameter (group or other type of parameter)
    • must be undo-able

Comment:

  • I don't see what is exactly a frame. In the current clfswm version there is only groups and windows (X window). A group can contains childs. A child is another group or an X window. Can you explain the need of frames? -- Philippe
    • Frame are the actual group in CLFSWM. I would like to use the term group for a more relaxed relationship that could be arbitrary as far as it is a DAG. For me, frame are a more constraint than group as far as membership is concerned (tree) because it is a geometrical relation. For example, you can use group to select any kind of frame even if there are not related by a geometry inclusion relation. -- Cyrille
      • Ah, ok I see. What do you think about a tag system on (actual) groups to do some actions on groups with no geometry relation. Another question: how do you want to represent children in your version of groups? How do you want to manipulate them? In the actual version the relation between childs is straightforward. -- Philippe
        • Actually, this user API is much more a programmatic interface than a user interface. I try to make it as orthogonal and generic as possible so that it could be a good foundation for user interfaces. I would second this with some tooling that would have a visual interface. -- Cyrille
          • I have asked on the ML -- Philippe

Facility API

API that the extension API rely on.

Comment:

Input

Concept:

  • input sequence: A list of sequential or combination of input event (example: C-a a) that can be recognized.

List of event:

  • mouse
    • motion
      • left
      • right
      • up
      • down
    • click
      • button (left, middle, right, 1, 2, 3, ...)
      • click type (simple, double, triple)
  • keyboard
    • key
    • modifier
  • Other event
    • On mouse enter
    • On focus (window)
    • On new member (frame or group membership)
    • ...

List of event combinator:

  • Simultaneous event (and)
  • Alternative event (or)
  • sequence of event

An input sequence is send to the window if one has a focus and if the input sequence is not recognized.

Comment:

  • Actually keys combination are done with a sub menu system. I think it's simple for the user to add its own keys combination and the info window helps to remember keys. So two systems are in place: shortcut (define-main-key/define-second-key) and menu (info-mode-menu). -- Philippe
    • This is only a definition of event. See the shortcut section for the binding between shortcut and operation, and the info menu -- Cyrille

Window management

Mode:

  • full: remove its own frame and group
  • window-only: without touching its own frame and group

Operations:

  • close
  • delete
  • destroy

Reference:

Comment:

Undo

Any operation of the extension API could be undone.

Convention:

  • If step is 0, proceed to the last mark
  • If step is superior to 1, proceed at last 'step' operations

Operations:

  • emacs-undo (&optional (step 1)): undo a la emacs
  • undo (&optional (step 1))
  • redo (&optional (step 1))
  • exclude-operation (operation): mark this operation has to be ignored for undo and redo. (For example, selection modification by default must be ignored)
  • include-operation (operation): mark this operation has to be undone or redone if asked.
  • history-size (step)
  • mark

Comment:

  • This is a nice idea (added in the TODO). But I don't really know already how to implement it now (save a state before each actions?). -- Philippe
    • Each operation of the extension API should register a reverse operation in a command stack. -- Cyrille

Naming

A group has a name unique for any membership it takes part to or a rank for each membership. The path (numbered or named) is its external identity (ie. seen by the user). Any operation of the extension API are applied to a group identified by its path in the DAG of group.

Accessor:

  • get-group-by-name (path)
  • get-frame-by-name (path): return the frame that its own group has this name if it exists such a frame
  • get-window-by-name (path): return the window that its own frame that its own group has this name if it exists such a window.

Comment:

  • What about numbers. A group is named and numbered. Name and numbers are not guaranted to be unique. There is a need for a function to ensure that name or numbers are unique (added in the TODO) -- Philippe.
    • I should change it to path. It is more consistent with the concept section -- Cyrille
      • Added in the TODO -- Philippe

Property group

The idea is to have special groups that if a group belong to, any of the member as a property of the group set and vice versa.

A property group as a property with a value. A property group behave like a group, that is a group can be a member of multiple property group.

Operation:

  • make-property (name property value)
  • change-property (property-group property value)

Comment:

Extension API

API that tries to be orthogonal.

Comment:

Focus

Handle the input focus (X window).

Operation:

  • focus-on (window)
  • no-focus: no window has the focus (X window)

Comment:

Geometry

This section describes the operations that a user can perform on a frame to change its geometry.

Mode:

  • linear: the change is done n pixels by n pixels
  • edge: the change is done until an edge/border is hit in the direction

Convention:

  • An increment of 0 means in edge mode
  • An increment superior to 1 means in linear mode

Operation:

  • move (frame &optional (increment 1))
    • left
    • right
    • up
    • down
  • resize (frame &optional (increment 1))
    • left border
      • grow/left
      • shrink/right
    • right border
      • grow/right
      • shrink/left
    • top border
      • grow/up
      • shrink/down
    • bottom border
      • grow/down
      • shrink/up

Comment:

  • Only groups have geometry. Windows are managed by a group. The geometry of a group is between 0 (left/top) and 1 (right/bottom).
    The user is asked for numbers between 0 and 100 when it need to specify a geometry. Then this numbers are converted in 0 to 1 before storage.
    For mouse actions. The geometry is done in pixel and then converted in float numbers (need a function to convert from and to float or pixel -> TODO).
    Actually there is some functions to find groups edges and you can manipluate x, y, h, w directly to change the geometry. Another thing, see the macro with-movement. -- Philippe
    • Ok for the implementation. I would like to change the term of the actual group in CLFSWM to be a frame which has more a geometrical meaning, group being more arbitrary. -- Cyrille

Layout manager

A layout manager handle the geometry of its children.

Type:

  • tile (row, column)
  • maximize
  • Stack tilling (percent (up, down, left right))
  • ...

Operation:

  • set-layout-manager (frame, type)

Nota:

  • Could be a property group

Comment:

Layer

Frames can sometimes be overlaid. A frame have a list of frame (frame-layer) to handler the order of exposure.

Operation:

  • put (frame): change the layer of the frame in the layer list of the parent
    • front
    • back
    • top
    • bottom

Nota:

  • Could be a property group

Comment:

  • This have to be implemented but for groups: raise/lower group (in the TODO). -- Philippe

Group management

A group is deleted if it has no more membership.

Accessor

  • list-children (group)
  • list-membership (group)

Operation

  • make-group (name parents &optional groups): There must be at least one parent to make a group. The name must be unique in all parents membership.
  • rename (group, new-name): the new name must not exist.
  • add (group, group): The second group become a child of the first group
  • remove (group, group): Remove the second group for the list of children of the first group
  • add-children (group, group): Add the children of the second group to the list of children of the first group. The list of children of the second group is not modified
  • merge (group, group): All the children of the second group are added to the first group. The second group is left empty.
  • move-child (group, child): change the place of the child group in the list of member of the group
    • previous
    • next
    • first
    • last

Comment:

Frame management

This section describes the operations that a user can perform on a frame.

Accessor:

  • list-children (frame)
  • parent (frame)

Operation:

  • make-frame (parent)
  • remove-frame (frame): Remove the frame from the children list of the parent, so deleting it.
  • move (frame)
    • parent
    • first sister
    • next aunt
  • move-child (frame): change the place of the frame in the children list of the parent
    • previous
    • next
    • first
    • last

Comment:

  • See question on top: is a frame really needed?
    • I think the geometry inclusion relation is a contraint because you could want to make operation on geometricaly unrelated frame. So, I propose to separate an arbitrary relation (group) and the geometrical relation (frame) -- Cyrille
      • Ok, asked on the ML -- Philippe

Hide

This section describes operations that a user can perform to show or hide a group meaning that it is not shown on the screen.

Accessor

  • hidden (group)

Operation:

  • hide (group)
  • show (group)

Nota:

  • Could be a property group

Comment:

  • How do you unhide a group when it is hidden? By name or number? -- Philippe
    • There should be a way to show the tree of frame and the DAG of group so that you can find the path to identify one, or at least the children of a frame or the member of a group. -- Cyrille

Window shadow

A window can be duplicated. The copy become a shadow of the copied window. An operation perform on one shadow does not impact the other shadow of the same window.

Accessor

  • list-shadow (window)

Operation

  • make-shadow (window)
  • remove-other-shadow (window): remove the other shadow but the one in parameter

Comment:

Shortcut

Concept:

  • mode: A mode is a list of shortcut. Its external identifier is its name.
  • shortcut: It is an input sequence associated to an operation

Accessor

  • list-shortcut (mode)
  • current-mode-name

Operation:

  • make-mode (name &key extend-modes overide-modes)
  • add-key-shortcut (mode, input-sequence, operation)
  • add-motion-shortcut (mode, input-sequence, operation)
  • add-escape-sequence (mode, input-sequence, input-sequence): The second input sequence is the one send to the application having the focus if the first input sequence is recognized.
  • set-current-mode (mode)

Shortcut assistant:

  • Show as a menu the list of possible keys that could be next typed

Comment:

  • This is done actually with the info-mode-menu. Is there a need to do something more sofisticated? -- Philippe
    • No, it was just to not miss it in this specification proposition -- Cyrille

Selection

Manage a special group named "*group-selection*" and a son of the group "*root*"

Accessor:

  • list-selection

Operation:

  • add (group)
  • remove (group)
  • clear

Comment:

  • Actually the selection is just stored in a list of childs. I think there is no need for a group to do that. -- Philippe
    • You might want to select different frame in different sub-trees. For example, to copy them in a new frame, so you have a new view. Frame cannot do that but group can. -- Cyrille
      • This is already doable in the current implementation: you can put a child from any group in the selection list. -- Philippe

Current frame

Handle a special group named "*current-frame*" containing only one frame that is the current one and a son of the group "*root*". It is a mean to navigate through the frame tree.

Accessor

  • current-frame-path

Operation:

  • set-current-frame (frame)
  • browse (set as current)
    • parent: set the current to the parent frame of the current one
    • first-child: set the current to the first child of the current one
    • last-child: set the current to the last child of the current one
    • next-sister: set the current to the first child of the next brother of the father of the current one.

Comment:

Zoom

Concept:

  • zoom out: Behave as if the application window is bigger for the application but completely drawn in a small amount of space (miniature). The zoom factor is inferior to 100%
  • zoom in: Behave as a magnifying glass. The zoom factor is superior to 100%. The part of the application window shown (viewport) can be moved.

Accessor:

  • zoom-factor (frame)

Operation:

  • set-zoom-factor (frame, factor)
  • move-viewport (frame &optional (increment 1))
    • left
    • right
    • up
    • down

Nota:

  • Could be a property group

Note:

  • Moving the viewport when the zoom factor is inferior to 100% has no effect.

Comment:

  • This is a nice idea but I don't know yet how to implement this. (-> In the TODO as maybe) -- Philippe

Discussion

  • If the structure of the page is OK for everybody, I would break it into smaller pages -- Cyrille Thouvenin
    • It's ok for me but without the frame level. I don't really see why frames are needed. -- Philippe
      • Ok I see what you mean by frame. I've asked for comments on the ML before doing anything. -- Philippe