= User API idea = [[PageOutline]] == Introduction == Here is some thought about an API for the users of [wiki:CLFSWM], because [wiki:CLFSWM] is meant to be a programmable window manager. This could be a categorized list of feature that [wiki: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 [http://en.wikipedia.org/wiki/Directed_acyclic_graph 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: * [http://www.afterstep.org/visualdoc.php?show=Functions 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 [http://en.wikipedia.org/wiki/Directed_acyclic_graph 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). [[BR]] 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. [[BR]] 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). [[BR]] 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