Return to repo list

smartlaunch

Contextual launcher/tag shortcut methodology; intended for dwm.
Return to HMagellan.com

README (6070B)


      1                                     - Smartlaunch -
      2 A method for contextually-aware rules-based application/tag view change shortcuts in dwm.
      3 
      4 01. What is Smartlaunch?
      5 
      6     Smartlaunch is a shell script and a set of instructions that are meant to be used in conjunction with
      7     dwm (https://dwm.suckless.org) to achieve a *certain kind of application launching behavior*. The project
      8     consists of two parts: a script that launches a command as long as no window matching a pair of given
      9     xproperties exists, and a set of instructions and examples on how to use this script with dwm to create
     10     keyboard shortcuts that can launch applications and then *function as quick ways to access those same
     11     application once they are already running* (for example, press MOD+F to launch Firefox, then press MOD+F
     12     again anytime to return immediately to the tag that Firefox was opened in, as long as Firefox is still there).
     13 
     14     The basic usage idea is to create a 'rule' in config.h (https://dwm.suckless.org/customisation/rules/) for 
     15     some application that you want to have a dedicated tag for (for instance, Firefox might be dedicated to tag 8, 
     16     meaning that every time you open an instance of Firefox, it will appear in tag 8), and then create a key 
     17     combination to launch that application *in the context of the smartlaunch script*, and to also link that same 
     18     key combination to a dwm command that causes you to shift your view to the tag associated with said application.
     19 
     20     Here is the step-by-step usage example:
     21 
     22         i. Create a rule for your application in config.h setting it to a specific tag
     23        ii. Create a command to launch that application using smartlaunch.sh in config.h
     24       iii. Create a key combination to launch that command in config.h
     25        iv. Also assign that same key combination to switch views to the application's tag in config.h
     26 
     27     Once this is done, you will have a context-aware shortcut for launching an application and viewing it
     28     immediately in the launched tab, as well as a way to *immediately switch to that same tab later as long as the
     29     application's window is still running.* If this sounds like desirable behavior to you, Smartlaunch can help!
     30 
     31 02. Installation & Dependencies
     32 
     33     There are no install instructions. Simply place the smartlaunch.sh script somewhere and then begin incorporating
     34     it into your config.h.
     35 
     36     Smartlaunch has the following dependencies:
     37 
     38         xwininfo
     39         xprop
     40         dwm (if you want to get any actual use out of the script)
     41 
     42     To install these on Gentoo, run:
     43         
     44         # emerge x11-apps/xwininfo x11-apps/xprop x11-wm/dwm
     45 
     46     These programs are also available on other distributions, or in source code format from https://freedesktop.org
     47     and https://dwm.suckless.org.
     48 
     49 03. Usage Instructions
     50 
     51     smartlaunch.sh takes three arguments:
     52         
     53         $1 - A command to launch.
     54         $2 - A string matching "WM_NAME" in the window created by the above command.
     55         $3 - A string matching *THE FIRST FIELD* of "WM_CLASS" in the window created by the above command.
     56 
     57     Here is an example:
     58 
     59         $ ./smartlaunch.sh firefox Firefox firefox
     60 
     61     The above example will launch the command 'firefox' if it cannot find any existing windows who's WM_NAME contain
     62     the string 'Firefox' and who's WM_CLASS contains 'firefox' in the first field. You may ask, "How do I find the 
     63     WM_NAME and WM_CLASS properties of a window?" The simplest way is to run xprop(1), then click on the window you 
     64     want to investigate. Both properties will be among the text in the output. It is important to NOT confuse 'WM_NAME'
     65     with '_NET_WM_NAME' or any similarly named property. Look only for the properties on lines beginning with 'WM_NAME'
     66     and 'WM_CLASS'.
     67 
     68     To include the above example in dwm's config.h, create a command that looks something like this:
     69 
     70        static const char *smartlaunchcmd[] = { "/bin/bash", "-c", "/path/to/smartlaunch.sh firefox Firefox firefox", NULL }
     71 
     72     This can be bound to a key combination in the 'keys[]' array in config.h. For instance, to bind it to MOD+F:
     73 
     74         { MODKEY,   XK_f,   spawn,  {.v = smartlaunchcmd } },
     75 
     76     The real use comes with creating a rule to assign the application window to a specific tag in the config.h
     77     'rules[]' array. For instance, to assign Firefox to tab 8:
     78 
     79         { "Firefox",    NULL,   NULL,   1 << 8,    0,   -1 },
     80 
     81     Once this is done, you can assign the same key combination from earlier to *also* switch to the tab associated
     82     with the application by the rule. For the examples listed above, that would mean including this *along with
     83     the first MOD+F shortcut* that we already made:
     84 
     85         { MODKEY,   XK_f,   view,   {.ui = 1 << 8 } },
     86 
     87     Notice that the key combination is *exactly* the same. In dwm, *all* entries for a specific key combination in
     88     the 'keys[]' array will be executed. They do not get overwritten.
     89        
     90     Now, when you press the chosen key combination (MOD+F in the examples), one of two things will happen:
     91 
     92         1). If there is no window matching the BOTH properties in the command, a new instance of the application
     93             will be started and the view will switch immediately to the tag associated with that application, or:
     94 
     95         2). If there IS a window matching BOTH of the properties in the command, the view will simply switch to 
     96             the tag associated with the existing application, and nothing new will be started.
     97 
     98     Refer to the file config.h.patch in this repository to see an example of the changes to be made to config.h
     99     to configure any given program to work with Smartlaunch.
    100 
    101 04. License
    102 
    103     Smartlaunch is licensed under the MIT/Expat license. See the LICENSE file for more details.
    104 
    105 05. Author
    106 
    107     Smartlaunch is developed and maintained by Erik Letson <hmagellan@hmagellan.com>. Please direct any questions,
    108     patches, or bug reports to his email.
    109 
    110     There is a browsable git repository for Smartlaunch available at https://git.hmagellan.com.