Data structures

Let’s look at ~/.workgroups file:

[cl-struct-wg-session "0G3A08BU1E35GEA0-18GPMY" ...
  ([cl-struct-wg-workgroup "0G3A08D8APKR11T4-1C1G10" "Tasks" ...
     [cl-struct-wg-wconfig "0GGI0JY4B3HD0WEO-86RSR3" ...
        [cl-struct-wg-wtree ...
           ([cl-struct-wg-win ...
            [cl-struct-wg-win ...

General info

All these structs (better to say functions to work with these objects) are created with wg-defstruct macro. For example for:

(wg-defstruct wg session
  (uid (wg-generate-uid))
  (field-2)
  ...

wg-defstruct creates functions like wg-make-session, wg-copy-session and wg-session-..., (to manipulate structures). Then you will have (wg-session-field-2 obj) and other defined fields to read properties of this object.

To set values (setf ...) function is used.

Example for current session object:

;; Read
(wg-session-file-name (wg-current-session))         ; Get a filename of current session
(wg-workgroup-parameters (wg-current-workgroup))    ; Get workgroup parameters

;; Write (used just before saving session to file)
(setf (wg-session-file-name (wg-current-session)) filename)    ; Set session filename
(setf (wg-session-version (wg-current-session)) wg-version)    ; Write workgroups version

Warning

Changing these defstructs themselves may break everyone’s session files. That’s why many of them have Parameters field. This one is exactly for extending saved information.

How to work with these structures?

Ok, we define a session structure, and you can get the value of it with (wg-current-session)

wg-defstruct creates functions like wg-session-..., wg-make-session (to manipulate structures). So if you have (wg-defstruct wg session ...) - then you have wg-session-file-name and other defined fields.

Session

The session object is the top level “class” that has workgroups in it.

(wg-defstruct wg session
  (uid (wg-generate-uid))
  (name)
  (modified)
  (parameters)
  (file-name)
  (version wg-version)
  (workgroup-list)
  (buf-list))

Note

List of buffers is a common pool for all workgroups. When you open a file (doesn’t matter in which workgroup) - the corresponding Buffer object will be added in wg-session-buf-list

Workgroup

workgroups contain frame states (that includes window configuration)

(wg-defstruct wg workgroup
  (uid (wg-generate-uid))
  (name)
  (modified)
  (parameters)
  (base-wconfig)
  (selected-frame-wconfig)
  (saved-wconfigs)
  (strong-buf-uids)
  (weak-buf-uids))

Wconfig

(wg-defstruct wg wconfig
  (uid (wg-generate-uid))
  (name)
  (parameters)
  (left)
  (top)
  (width)
  (height)
  (vertical-scroll-bars)
  (scroll-bar-width)
  (wtree))

What’s the difference between wconfig and wtree? Well a workgroup can have several wconfigs (buffer layouts). But to keep it simple let’s say each workgroup has only 1 wconfig.

wconfig = wtree + additional parameters

Wtree

(wg-defstruct wg wtree
  (uid)
  (dir)
  (edges)
  (wlist))

Win

(wg-defstruct wg win
  (uid)
  (parameters)
  (edges)
  (point)
  (start)
  (hscroll)
  (dedicated)
  (selected)
  (minibuffer-scroll)
  (buf-uid))

Buffer

Parameters

Changing main structures may lead to huge problems in compatibility. That’s why there are parameters for Session, Workgroup, Wconfig and Win objects. They allow you to save your custom data.

For example to set (key, value) pair for current workgroup:

;; Write (key, value)
(wg-set-workgroup-parameter
 'ecb                                            ; name
 (and (boundp 'ecb-minor-mode) ecb-minor-mode))  ; value

Usually these functions are called like:

wg-<object>-parameter          ; to read
wg-set-<object>-parameter      ; to set
wg-remove-<object>-parameter   ; to remove parameter

For session: wg-session-parameter, wg-set-session-parameter, wg-remove-session-parameter For workgroup: wg-workgroup-parameter, wg-set-workgroup-parameter, wg-remove-workgroup-parameter