docs » BonjourLauncher

Set whether the BonjourLauncher chooser window should apoear dark themed, aqua themed (light) or track the current system settings for Dark mode. Defaults to nil.

This should be a boolean specifying whether the BonjourLauncher chooser window should appear in dark mode (true) or not (false). If set to nil, the chooser will track the current system settings for Dark mode.

Whether or not to display a toolbar at the top of the BonjourLauncher chooser window. Defaults to true.

This boolean variable determines if the toolbar which allows changing the currently visible service type is displayed when the BonjourLauncher chooser window is presented. If you set this to false then you will only be able to change the currently visible services with the BonjourLauncher:show(serviceType) and BonjourLauncher:toggle(serviceType) methods.

The number of rows to display when the chooser is visible. Defaults to 10.

Set this variable to an integer to specify the number of rows of choices to display when the BonjourLauncher chooser window is visible. Set it to nil to revert to the default.

Sets the color of the subText for each service listed in the BonjourLauncher chooser window. Defaults to nil.

This should be a table representing a color as defined by the hs.drawing.color module documentation, or nil to revert to the hs.chooser module default.

You can override this on a per template basis by including the subTextColor field in the service type definition. See BonjourLauncher.templates.

A table specifying the service types which the BonjourLauncher looks for on your network and defines how to display and launch discovered services.

Notes:

• This table should be an array of tables, with each table in the array specifying a service type.

• Changes to this variable will be reflected the next time the BonjourLauncher chooser window is shown -- if it is currently visible when changes are made, the new changes will NOT be reflected in the currently open chooser.

• Each service type table entry should contain one or more of the following keys:

  • type - a required string specifying the type of advertisement to search for with this entry. Example service types can be seen in hs.bonjour.serviceTypes.
  • label - an optional string, defaulting to the value for type, specifying the label for the toolbar item under which these advertised services are collected in the BonjourLauncher chooser window. May or may not be displayed if you have customized the toolbar's visual properties. Note that this field is used for internally identifying different template views, so it must be unique among the template entries where disabled is false or undefined.

  • image - an optional hs.image object specifying the image to display for the toolbar item under which these advertised services are collected in the BonjourLauncher chooser window. May or may not be displayed if you have customized the toolbar's visual properties.

  • text - an optional string, defaulting to "%name%", specifying the text to be displayed for each advertised service listed in this collection in the BonjourLauncher chooser window.

  • subText - an optional string, specifying the sub-text to be displayed for each advertised service listed in this collection in the BonjourLauncher chooser window.

  • filter - an optional function which can be used to filter out advertised services which you do not wish to include in the chooser window. The function should expect two parameters, the hs.bonjour.service object for the discovered service and a table containing all of the key-value pairs of the service template with values expanded to describe what is known about this specific service. The filter function should return true if the service is to be included or false if the service is to be omitted.

  • fn - The function to invoke. This function should expect two arguments, the hs.bonjour.service object for the selected service and a table containing all of the key-value pairs of the service template with values expanded to describe what is known about this specific service. Any return value for the function is ignored. If this is present, url and cmd will be ignored by the default handler, though they may be accessed through the second argument to the function.

  • url - The url to open with hs.urlevent.openURL. If this is present, cmd is ignored.

  • cmd - The command to execute with hs.execute.

  • hidden - an optional boolean, default false, that can be used to specify that the service list should not be displayed in the toolbar by default. You can still access these service types by specifying them as arguments to the BonjourLauncher:show or BonjourLauncher:toggle methods, or by creating a psuedo-key for the service type with BonjourLauncher:bindHotkeys. If the user customizes the toolbar by right-clicking on it, they can add this service to the toolbar, but it won't be in the default list.

  • disabled - an optional boolean, default false, specifying that this service should be skipped entirely is not available for viewing by any means.

  • textColor - an optional color table as defined in the hs.drawing.color module documentation to be used for the text displayed for each discovered service when this template is being displayed in the BonjourLauncher chooser. If not present, the color specified for BonjourLauncher.textColor will be used.

  • subTextColor - an optional color table as defined in the hs.drawing.color module documentation to be used for the sub-text displayed for each discovered service when this template is being displayed in the BonjourLauncher chooser. If not present, the color specified for BonjourLauncher.subTextColor will be used.

  • Additional key-value pairs do not have special meaning for this spoon but kay-value pairs with a string for the value will be included in the second argument passwd to fn, if present.

• Note that only type and one of url, cmd, or fn must be provided -- everything else is optional.

• For all keys, except for type and label, in the template definition which have string values, the following substring patterns will be matched and replaced as described below:

  • %address% - Will be replaced with the first address discovered for the service when it is resolved.
    • %address4% - Variant of %address% which is replaced with the first IPv4 address or "n/a" if one cannot be found or has not been discovered yet.
    • %address6% - Variant of %address% which is replaced with the first IPv6 address or "n/a" if one cannot be found or has not been discovered yet.
  • %domain% - Will be replaced with the domain the service was found in, usually "local."
  • %hostname% - Will be replaced with the hostname on which the service is being offered
  • %name% - Will be replaced with the name of the advertised service.
  • %port% - Will be replaced with the port number on the machine that the service is provided on.
  • %txt:<key>% - Will be replaced with the value for the specified <key> of the text records associated with the service, or an empty string if no such key is present. To see the list of text record key-value pairs for a specific service, you can right click on it while it is being displayed in the BonjourLauncher chooser window (press the escape key to clear it).

Sets the color of the primary text for each service listed in the BonjourLauncher chooser window. Defaults to nil.

This should be a table representing a color as defined by the hs.drawing.color module documentation, or nil to revert to the hs.chooser module default.

You can override this on a per template basis by including the textColor field in the service type definition. See BonjourLauncher.templates.

The width of the BonjourLauncher chooser window as a percentage of the screen size. Defaults to 40.

Set this variable to a numeric value between 1 and 100 to specify the percentage of screen the screen's width the BonjourLauncher window should occupy when visible. Set it to nil to revert to the default.

Add predefined recipes to BonjourLauncher.templates for display by the BonjourLauncher chooser.

Paramters:

• recipe, ... - One or more string values matching a variable name in BonjourLauncher.recipes which define basic templates for common services which you may wish to add to your BonjourLauncer chooser window.

Returns:

• the BonjourLauncer object

Notes:

• This method is basically a wrapper which performs table.insert(spoon.BonjourLauncher.templates, spoon.BonjourLauncher.recipes.*recipe*) for each of the recipe names specified as a parameter to this method. You may invoke this method multiple times or combine multiple recipes into one invocation by specifying more thane one string, each separated by a comma.

Binds hotkeys for the BonjourLauncher spoon

Parameters:

• mapping - A table containing hotkey modifier/key details for one or more of the following commands:
  • "show" - Show the BonjourLauncher chooser window
  • "hide" - Hide the BonjourLauncher chooser window
  • "toggle" - Toggles the visibility of the BonjourLauncher window

Returns:

• the BonjourLauncher spoon object

Notes:

• the mapping table is a table of one or more key-value pairs of the format command = { { modifiers }, key } where:

  • command - is one of the commands listed above
  • modifiers - is a table containing keyboard modifiers, as specified in hs.hotkey.bind()
  • key - is a string containing the name of a keyboard key, as specified in hs.hotkey.bind()

• Psuedo keys for show and toggle are also supported which can be used to generate hotkeys which will take you to a specific list of services when the BonjourLauncher chooser is displayed. The format of these psuedo keys is <function>_<label> where <label> matches the label field of a specific entry in BonjourLauncher.templates; for example:

   BonjourLauncher:bindHotkeys({
       -- create a general toggle hotkey
       toggle     = { { "cmd", "ctrl", "alt"}, "=" },
       -- create a hotkey which will open the chooser to the SSH display, or
       -- change to it if another service type is currently being viewed. If the
       -- SSH display is currently being viewed, closes the chooser window (i.e.
       -- "toggle")
       toggle_SSH = { { "cmd", "ctrl", "alt" }, "s" }
   })

Hides the BonjourLauncher chooser window and clears any active service queries.

Parameters:

• None

Returns:

• the BonjourLauncher spoon object

Shows the BonjourLauncher chooser window and begins queries for the currently selected service type.

Parameters:

• label - an optional string specifying the label field of a template defined in BonjourLauncher.templates for a specific service type to show in the chooser window. Defaults to the last selected service type previously viewed or the first one defined in BonjourLauncher.templates if this is the first invocation.

Returns:

• the BonjourLauncher spoon object

Notes:

• Automatically invokes BonjourLauncher:start() if this has not already been done.

• Service queries are grouped by type and the currently visible items can be changed by clicking on the type icon or label in the chooser toolbar if BonjourLauncher.displayToolbar is true.

Readys the chooser interface for the BonjourLauncher spoon

Parameters:

• None

Returns:

• the BonjourLauncher spoon object

Notes:

• This method is included to conform to the expected Spoon format; it will automatically be invoked by BonjourLauncher:show if necessary.

Removes the chooser interface for the NonjourLauncher spoon and any lingering service queries

Parameters:

• None

Returns:

• the BonjourLauncher spoon object

Notes:

• This method is included to conform to the expected Spoon format; in general, it should be unnecessary to invoke this method directly as service queries are cleared any time an item is selected from the chooser window or the window closes.

Toggles the visibility of the BonjourLauncher chooser window.

Parameters:

• label - an optional string specifying the label field of a template defined in BonjourLauncher.templates for a specific service type to show or switch to in the chooser window, if the window is already open and the label of the service type currently on display differs.

Returns:

• the BonjourLauncher spoon object

Notes::

• If the chooser window is currently visible, this method will invoke BonjourLauncher:hide; otherwise invokes BonjourLauncher:show.