User API idea

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:

• ​Afterstep functions

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