Extend ws session

The whole idea is that you should be able to write your own wrappers for your favourite applications or the wm you use. If there exists a file in $S_CONFIG_FOLDER/{app,wm} it will be sourced instead of a file with the same name in $S_LIB_FOLDER/{app,wm}.

Global variables

You must not change the value of a global variable in any of the app, wm or bin files. There are getting set in the core/ and the test/ files or they are user settings which are loaded from the rc file. You can use/access those from whithin all files/functions you want to write.

You can print the value of a variable with ws-session print S_VARIABLE_NAME

S_WM

This is a list of your preferred window manager(s). Can be one or more and it get's truncated to the running wm.

Can be set in the rc file. But it gets set automatically otherwise.

S_APPLICATIONS

Array with the applications you want open and close with this script.

Must be set in the rc file.

S_LIB_FOLDER

Points to the folder with all the code in it. Defaults to but /usr/lib/ws-session. You can export this variable to your env to use a different install directiory.

Leave it out or set this like your other environement variables. You can just export it for testing purposes.

S_CONFIG_FOLDER

Defaults to $XDG_CONFIG_HOME/ws-session, but if you name your rc file $HOME/.ws-session.rc you can set this to wathever you like

Can be set in the rc file.

S_DATA_FOLDER

Per default points to $XDG_DATA_HOME/ws-session. Here is all the data from saved sessions.

Can be set in the rc file.

S_TEMP_FOLDER

In this directory all the runtime data is stored. When you load a session the data gets copied from S_DATA_FOLDER/sessionname-1 to S_TEMP_FOLDER/sessionname and vice versa Default: /tmp/ws-session-$(whoami).

Can be set in the rc file.

S_NUMBER_OF_BACKUPS

How many backups of a session should get stored in S_DATA_FOLDER. Default 5.

Can be set in the rc file.

S_DEFAULT_TAG

If you close a session your window manager changes to this workspace.

Name it 1 or arch or whatever. There is no default.

S_SEL_TAG

Contains the active workspace.

Do not set this variable in the rc file, it gets set automatically.

S_MENU

Points to your favorite menu e.g. dmenu -nf #333 but can also be another menu application.

Can be set in the rc file.

S_WM_SUPPORTS_LAYOUT_SAVING

1 if the wm is able to save and load a layout and 0 otherwise.

Do not set this variable in the rc file, it gets set it in the wm/* files.

S_LOAD_LAYOUT_SLEEP

After running all applications one has to wait until all the windows are created before the layout can get reloaded.

It depends on your hardware. Can be set in the rc file.

S_LOAD_ACTION_SLEEP

After closing all applications one has to wait until all the data is stored before the system action (eg. reboot) can take place.

It depends on your hardware. Can be set in the rc file.

S_SHELL_FILES

An array of file names for your shell. It could be the history and other shell files (eg dirstack) without the dot. This array is used in the functions of app/urxvt.sh there might be a app/xterm.sh where this array could be used too.

Can be set in the rc file.

Window Manager

• To use the wm tests: You can use the command TEST_TAG=session test/test-core-wm.sh if you are developping on a tag named session. It defaults to a tag named 1.

• Copy wm/is-wm-running.sh to your $S_CONFIG_FOLDER/wm folder and add a test for your wm. The function should echo something if it's running and nothing if not.

• Create a new file $S_CONFIG_FOLDER/wm/examplewm.sh with the functions:

# returns current tag
s_seltag_examplewm() {
}

# create a new tag with name "$@" and switch to it
# dont create the tag if there is already one with that name
s_newtag_examplewm() {
}

# switch to $S_DEFAULT_TAG and remove $S_SEL_TAG
s_closetag_examplewm() {
}

# list all open tags
s_list_open_tags_examplewm() [
}

# list winid and class of all open windows on $S_SEL_TAG
s_list_app_seltag_examplewm() {
  for client in $(get a list of all winids on $S_SEL_TAG) ; do
    s_print_id_class $client
  done
  unset client
}

# focus a window by its winid "$@"
s_focus_window_examplewm() {
}

# if the following variable is set to 1 ws-session tries to save
# and reload the layout.
S_WM_SUPPORTS_LAYOUT_SAVING="0"

# save the layout, the windowids will get replaced with the new
# ones when you start the session.
s_save_layout_examplewm() {
}

# reload the layout. The file in $1 contains the stored layout
# with the new windowids.
s_reload_layout_examplewm() {
}

• Run the wm tests until they dont throw wrong output and no tag with name tagname exists afterwards.
• You can run one function with ws-session debug s_function_name argument

Application

• Create a new file bin/exampleapp to run the wrapper.
• Create a new file app/exampleapp.sh with the functions:

# open exampleapp from data folder, lockfiles and state should 
# be stored in the temporary folder.
# $1:       Data folder: where the last session was stored.
# $tmp_dir: Temp folder: where the new session is.
s_exampleapp_open_session() {
  # restore some files (this is just an example).
  cp "$1/exampleapp.winid" "$tmp_dir"
  # you have to start the application.
  command with -arguments & >/dev/null 2>&1
  pid="$!"
  # you want to save the old windowid and the pid to be able to restore the layout.
  s_reg_winid "$pid" "$(< $tmp_dir/exampleapp.winid)"
}

# close exampleapp, save state to temporary folder
# $1:       winids of all exampleapps on current tag.
# $tmp_dir: save things here 
s_exampleapp_close_session() {
  # you want to save the actual windowid(s) to reload the layout.
  # This is just an example:
  echo "$1" > "$tmp_dir/exampleapp.winid"
}

# start exampleapp in a way that close_session can close/save it
# use $S_TEMP_FOLDER/$S_SEL_TAG not $tmp_dir
s_exampleapp_start() {
}

• Run test/test-app.sh exampleapp. The application gets started and you can 'do' something e.g. open a website. Then you select the window with the mouse and the exampleapp will be stopped and started again. It works, when the things you 'did' will get reloaded. Kill the window with another mouse click.

Sometimes bin/exampleapp and s_exampleapp_start are not needed but exampleapp needs a setting in its config files, eg. urxvt.