[sawfish] Improvements in doc on apps-menu. One minor fix in filtering.
- From: Christopher Bratusek <chrisb src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [sawfish] Improvements in doc on apps-menu. One minor fix in filtering.
- Date: Tue, 1 Mar 2011 13:10:19 +0000 (UTC)
commit 0d4c407c4faf1b7bfe0af56aaa6ebc4cb4e83566
Author: Teika kazura <teika lavabit com>
Date: Tue Mar 1 13:34:41 2011 +0900
Improvements in doc on apps-menu. One minor fix in filtering.
- In apps-menu-filter, it was attempted to accept a lisp expression.
It is deleted, since it didn't work, and it was useless since
the expression can't receive the desktop entry list to process.
- news.texi and OPTIONS are updated, too.
- It includes whitespace fix.
OPTIONS | 14 +--
lisp/sawfish/wm/ext/apps-menu.jl | 180 +++++++++++------------
man/news.texi | 16 ++-
man/sawfish.texi | 303 +++++++++++++++++++++-----------------
4 files changed, 272 insertions(+), 241 deletions(-)
---
diff --git a/OPTIONS b/OPTIONS
index e170414..09635c0 100644
--- a/OPTIONS
+++ b/OPTIONS
@@ -174,16 +174,10 @@
;; "Your own applications menu entries. It is followed by auto generated
;: applications menu.")
-;; (defvar-setq apps-menu-show-all nil
-;; "Some entries are hidden from the menu, for example GNOME specific
-;; applications like eog, nautilus or evince.
-;;
-;; Settings this variable to 'nil will generate
-;; a menu that honours NoDisplay, Hidden OnlyShowIn and NotShowIn fields.
-;; In other words it generates the same menu like GNOME or KDE.
-;; If this variable is set to 'maybe the NoDisplay and Hidden fields are
-;; ignored, while NotShowIn and OnlyShowIn are respected.
-;; At last if you choose 't all four fields are ignored.")
+;; (defvar-setq apps-menu-filter 'default
+;; "The filter to use while generating `apps-menu'. It can be
+;; a symbol `default', `some', a function, or nil. See the info manual
+;; \"Applications Menu\" section for the full description.")
;; (defvar-setq desktop-directory '("/usr/share/applications")
;; "List of directories to look for *.desktop files")
diff --git a/lisp/sawfish/wm/ext/apps-menu.jl b/lisp/sawfish/wm/ext/apps-menu.jl
index 4a96a6d..a217f91 100644
--- a/lisp/sawfish/wm/ext/apps-menu.jl
+++ b/lisp/sawfish/wm/ext/apps-menu.jl
@@ -58,7 +58,7 @@
sawfish.wm.menus
sawfish.wm.commands
sawfish.wm.commands.launcher)
-
+
(define-structure-alias apps-menu sawfish.wm.ext.apps-menu)
;; User Options
@@ -73,11 +73,11 @@ applications menu.")
(defvar apps-menu-filter 'default
"The filter to use while generating the `apps-menu'. The default filters
-include `fdo-toplevel-filter' `fdo-nodisplay-filter' `fdo-hidden-filter'
-`fdo-onlyshowin-filter' and `fdo-notshowin-filter'. Can also be set with
-'default or 'some, both of which are combinations of the default filters,
-'default uses them all and 'some only uses `fdo-notshowin-filter' and
-`fdo-onlyshowin-filter'. This can be set to 'nil or '() to perform no
+include `fdo-toplevel-filter' `fdo-nodisplay-filter' `fdo-hidden-filter'
+`fdo-onlyshowin-filter' and `fdo-notshowin-filter'. Can also be set with
+'default or 'some, both of which are combinations of the default filters,
+'default uses them all and 'some only uses `fdo-notshowin-filter' and
+`fdo-onlyshowin-filter'. This can be set to 'nil or '() to perform no
filtering on the `apps-menu'.")
(defvar apps-menu-associate-categories t
@@ -90,7 +90,7 @@ filtering on the `apps-menu'.")
"Sort the apps menu alphabetically.")
(defvar apps-menu-lang nil
- "Language for applications menu, in string. Default is set from locale.")
+ "Human language for applications menu, in string. Default is set from locale.")
;; The Master Category List
@@ -130,7 +130,7 @@ filtering on the `apps-menu'.")
"FileManager" "X-FileSystemMount" "Compression"))
("System" . ("X-SystemSchedule" "System" "X-SystemMemory" "Emulator"
"TerminalEmulator" "Printing" "Monitor" "Security"))
- ("Settings" . ("Settings" "HardwareSettings" "PackageManager"
+ ("Settings" . ("Settings" "HardwareSettings" "PackageManager"
"X-GNOME-PersonalSettings" "DesktopSettings"))
("Exiles" . ("Exile"))))
@@ -144,7 +144,7 @@ filtering on the `apps-menu'.")
"Return `t' if `instring' should be skipped."
(or (eq (aref instring 0) ?#)
(eq (aref instring 0) ?\n)))
-
+
(define (check-if-desktop-stream instream)
"Check for the `[Desktop Entry]' line in `instream'"
(let ((line (read-line instream)))
@@ -153,7 +153,7 @@ filtering on the `apps-menu'.")
't
(when (fdo-skip-line-p line)
(check-if-desktop-stream instream))))))
-
+
(define (desktop-file-p directory-file)
"Quickly check if `directory-file' is a `*.desktop' file."
(condition-case nil
@@ -161,9 +161,9 @@ filtering on the `apps-menu'.")
(check-if-desktop-stream this-file))
;; unreadable -> return nil
(file-error)))
-
+
(define (get-key-value-pair instring)
- "Split a `*.desktop' file line into it's key-value pair.
+ "Split a `*.desktop' file line into its key-value pair.
Returns (key . value)"
;; Sorry, \\s doesn't work. Why??
(if (string-match "^([^ \t=]+)[ \t]*=[ \t]*([^\n]+)" instring)
@@ -172,11 +172,11 @@ Returns (key . value)"
(cons "" "")))
(define (fdo-group-p instring)
- (eq (aref instring 0) ?\[))
+ (eq (aref instring 0) ?\[))
(define (get-fdo-group instring)
(substring instring 1 (- (length instring) 2)))
-
+
(define (parse-fdo-file-line infile)
"Parse a `*.desktop' file list.
Returns (group1 (key1 . value1) ... group2 (keyA . valueA) ...)"
@@ -194,9 +194,9 @@ Returns (group1 (key1 . value1) ... group2 (keyA . valueA) ...)"
(when (desktop-file-p infile)
(let ((d-file (open-file infile 'read)))
(parse-fdo-file-line d-file))))
-
+
;; desktop-file mapping
-
+
(define (map-desk-files in-desk-files in-directory #!optional (extension "."))
"Given a list of filenames and a directory, will expand those
filenames to include the full path."
@@ -205,7 +205,7 @@ filenames to include the full path."
(cons (expand-file-name (car in-desk-files) in-directory)
(map-desk-files (cdr in-desk-files) in-directory extension))
(map-desk-files (cdr in-desk-files) in-directory extension))))
-
+
(define (map-dir-files directories #!optional (extension "."))
"Given a list of directory paths, will return a list of
files in those direcories with their full pathnames. Optionally
@@ -227,7 +227,7 @@ files in those direcories with their full pathnames. Optionally
(defmacro simplify-mlang (mlang mlevel)
`(and
- ,(cond
+ ,(cond
((or (= 0 mlevel) (not mlevel))
`(or (string-looking-at "([a-z]*)(_?)([A-Z]*?)(@)([A-Z]*[a-z]*)?" ,mlang)
(string-looking-at "([a-z]*)(_..)|([a-z]*)?" ,mlang)
@@ -242,10 +242,10 @@ files in those direcories with their full pathnames. Optionally
(define (find-lang-string)
(let loop ((lang-vars '("LC_ALL" "LC_MESSAGES" "LANG")))
- (and lang-vars
- (let ((mlang (getenv (car lang-vars))))
- (if mlang (simplify-mlang mlang 0)
- (loop (cdr lang-vars)))))))
+ (and lang-vars
+ (let ((mlang (getenv (car lang-vars))))
+ (if mlang (simplify-mlang mlang 0)
+ (loop (cdr lang-vars)))))))
;; Functions for categories
@@ -258,55 +258,55 @@ files in those direcories with their full pathnames. Optionally
(define (merge-list input delimiter)
"Merge a cons list `input' into a string separated by `delimiter'"
(when input
- (concat (car input) delimiter
+ (concat (car input) delimiter
(merge-list (cdr input) delimiter))))
(define (associate-categories fdol)
- "Associate the `Categories' value(s) with the category
+ "Associate the `Categories' value(s) with the category
master list, `desktop-cat-alist'. Returns a modified desktop-file entry."
(when fdol
- (let* ((these-categories
- (delete "" (string-split ";" (cdr (assoc "Categories" fdol)))))
- (category-list '()))
+ (let* ((these-categories
+ (delete "" (string-split ";" (cdr (assoc "Categories" fdol)))))
+ (category-list '()))
(let loop ((this-category these-categories))
- (if (null this-category)
- (let ((cat-string (merge-list (remove-duplicates category-list) ";")))
- (rplacd (assoc "Categories" fdol)
- cat-string)
- fdol)
- (progn (mapc (lambda (ent)
- (if (member (car this-category) ent)
- (setq category-list
- (append category-list (list (car ent))))))
- desktop-cat-alist)
- (loop (cdr this-category))))))))
+ (if (null this-category)
+ (let ((cat-string (merge-list (remove-duplicates category-list) ";")))
+ (rplacd (assoc "Categories" fdol)
+ cat-string)
+ fdol)
+ (progn (mapc (lambda (ent)
+ (if (member (car this-category) ent)
+ (setq category-list
+ (append category-list (list (car ent))))))
+ desktop-cat-alist)
+ (loop (cdr this-category))))))))
(define (grab-category input cat)
- "Remove duplicate categories from a generated apps-menu list by
+ "Remove duplicate categories from a generated apps-menu list by
category name."
(when input
(let ((cat-list '()))
(setq cat-list (append cat-list (list cat)))
(let loop ((this-line input))
- (if (not this-line) cat-list
- (progn (if (string= (caar this-line) cat)
- (setq cat-list (append cat-list (list (cdr (car this-line))))))
- (loop (cdr this-line))))))))
+ (if (not this-line) cat-list
+ (progn (if (string= (caar this-line) cat)
+ (setq cat-list (append cat-list (list (cdr (car this-line))))))
+ (loop (cdr this-line))))))))
(define (make-category-list input)
"Return a list of the categories to be used in the menu."
(when input
(cons (caar input)
(make-category-list (cdr input)))))
-
- (define (consolodate-menu input)
- "Reduce the menu down so that each menu entry is inside a
+
+ (define (consolidate-menu input)
+ "Reduce the menu down so that each menu entry is inside a
single category."
(when input
(let ((cat-list (remove-duplicates (make-category-list input)))
(out-menu nil))
(mapc (lambda (x)
- (setq out-menu
+ (setq out-menu
(append out-menu
(list (remove-duplicates (grab-category input x))))))
cat-list)
@@ -323,8 +323,8 @@ single category."
"Alphabetize the entries in the category menus."
(if saw-menu
(cons (cons (car (car saw-menu))
- (sort (cdr (car saw-menu))
- (lambda (a b)
+ (sort (cdr (car saw-menu))
+ (lambda (a b)
(string< (string-downcase (car a)) (string-downcase (car b))))))
(alphabetize-entries (cdr saw-menu)))))
@@ -357,7 +357,7 @@ with caution, file may be corrupt.\n"))
(not (assoc (concat name-string apps-menu-lang "]") fdo-list)))
(setq fdo-list (append fdo-list (cons (cons "Name" "Unknown")))))
fdo-list))
-
+
(define (fdo-check-exile fdo-list)
"If `fdo-list' doesn't have a Categories, Exec, or Name field,
exile it."
@@ -383,7 +383,7 @@ exile it."
(not (stringp (cdr (assoc "Category" fdo-list)))))
(rplacd (assoc "Category" fdo-list) "Exile"))
(append fdo-list (cons (cons "Category" "Exile")))))
- fdo-list)
+ fdo-list)
(define (determine-desktop-name fdo-list)
"Get the correct Name[*] entry based on language settings."
@@ -420,7 +420,7 @@ not present in the desktop-file-list"
(if (string-match "[Ff]" (cdr (assoc "NoDisplay" fdol)))
fdol)
fdol))
-
+
(define (fdo-hidden-filter fdol)
"Return the desktop-file-list if Hidden is False, or if Hidden is
not present in the desktop-file-list"
@@ -430,7 +430,7 @@ not present in the desktop-file-list"
fdol))
(define (fdo-onlyshowin-filter fdol)
- "Return the desktop-file-list if OnlyShowIn matches `desktop-environment',
+ "Return the desktop-file-list if OnlyShowIn matches `desktop-environment',
or if OnlyShowIn is not present in the desktop-file-list"
(if (assoc "OnlyShowIn" fdol)
(if (string-match desktop-environment (string-downcase (cdr (assoc "OnlyShowIn" fdol))))
@@ -438,7 +438,7 @@ or if OnlyShowIn is not present in the desktop-file-list"
fdol))
(define (fdo-notshowin-filter fdol)
- "Return the desktop-file-list if NotShowIn does not match `desktop-environment',
+ "Return the desktop-file-list if NotShowIn does not match `desktop-environment',
or if NotShowIn is not present in the desktop-file-list"
(if (assoc "NotShowIn" fdol)
(if (not (string-match desktop-environment (string-downcase (cdr (assoc "NotShowIn" fdol)))))
@@ -454,7 +454,7 @@ desktop-entry through `fdo-associate-categories'."
fdol)))
(define (fdo-toplevel-filter fdol)
- "Return the desktop-file-list if the `Category' is of the
+ "Return the desktop-file-list if the `Category' is of the
Top-Level variety."
(when fdol
(if (not (equal "Top-Level" (cdr (assoc "Category" fdol))))
@@ -475,32 +475,30 @@ the NotShowIn and OnlyShowIn keys."
(fdo-notshowin-filter
(fdo-onlyshowin-filter fdol))))
- (define (fdo-filter-record fdol display-test)
- "Return the result of `display-test' which can be a pre-set filter,
-such as `default' or `some' or it can be a pre-defined function of
-your choosing, which should either return the desktop-file-list or '().
-If `display-test' is not defined, will return the input desktop-file-list."
- (if (not display-test) fdol
+ (define (fdo-filter-record fdol filter)
+"Let `filter' process `fdol', a desktop file entry, and return the result.
+`filter' can be a function, or a symbol 'default or 'some. If it isn't set,
+return `fdol' as-is."
+ (if (not filter) fdol
(condition-case nil
(let loop ((fdo-entry fdol))
- (when (consp fdo-entry)
- (cons
- ;; Check if entry is valid
- (fdo-double-check-category
- (fdo-check-exile
- ((cond
- ;; default filter is chosen
- ((equal display-test 'default)
- fdo-default-filter)
- ;; some flter is chosen
- ((equal display-test 'some)
- fdo-some-filter)
- ;; user filter is chosen
- ((closurep display-test)
- display-test)
- (t `progn))
- (car fdo-entry))))
- (loop (cdr fdo-entry)))))
+ (when (consp fdo-entry)
+ (cons
+ ;; Check if entry is valid
+ (fdo-double-check-category
+ (fdo-check-exile
+ ((cond
+ ;; default filter is chosen
+ ((equal filter 'default)
+ fdo-default-filter)
+ ;; some flter is chosen
+ ((equal filter 'some)
+ fdo-some-filter)
+ ;; user filter is chosen
+ ((closurep filter)
+ filter))
+ (car fdo-entry))))
+ (loop (cdr fdo-entry)))))
(error fdol))))
(define (split-desktop-entry fdol)
@@ -512,10 +510,10 @@ of the categories of the original."
(when (stringp category-string)
(let loop ((categories
(delete "" (string-split ";" category-string))))
- (when categories
- (append (list
- (append new-fdol (list (cons "Category" (car categories)))))
- (loop (cdr categories)))))))))
+ (when categories
+ (append (list
+ (append new-fdol (list (cons "Category" (car categories)))))
+ (loop (cdr categories)))))))))
;; Sawfish-menu generation
@@ -523,7 +521,7 @@ of the categories of the original."
"Return menu-entry list from a fdo-list."
;; Generate the menu-entry list
(generate-menu-entry
- ;; Filter entry by pre-made or user function
+ ;; Filter entry by pre-made or user function
(delete nil
(fdo-filter-record
;; Split the desktop-entry by category
@@ -539,9 +537,9 @@ of the categories of the original."
desktop file `desk-file'."
(when (car fdo-list)
(cons (list (cdr (assoc "Category" (car fdo-list)))
- (determine-desktop-name (car fdo-list))
- (determine-desktop-exec (car fdo-list)))
- (generate-menu-entry (cdr fdo-list)))))
+ (determine-desktop-name (car fdo-list))
+ (determine-desktop-exec (car fdo-list)))
+ (generate-menu-entry (cdr fdo-list)))))
(define (generate-apps-menu)
"Returns the list of applications menu which can be used for `apps-menu'."
@@ -549,7 +547,7 @@ desktop file `desk-file'."
(setq apps-menu-lang (find-lang-string)))
(let ((desk-files (flatten (map-dir-files desktop-directory ".desktop")))
(local-menu nil))
- (mapc
+ (mapc
(lambda (x)
(setq local-menu
(append local-menu
@@ -557,8 +555,8 @@ desktop file `desk-file'."
(parse-fdo-file x)))))
desk-files)
(if apps-menu-alphabetize
- (alphabetize-entries (consolodate-menu (sort (delete nil local-menu) string<)))
- (consolodate-menu (sort (delete nil local-menu) string<)))))
+ (alphabetize-entries (consolidate-menu (sort (delete nil local-menu) string<)))
+ (consolidate-menu (sort (delete nil local-menu) string<)))))
(define (init-apps-menu)
"If `apps-menu' is nil, then call `update-apps-menu'. This function
@@ -575,4 +573,4 @@ append the auto generated one."
(setq apps-menu user-apps-menu)))
(define-command 'update-apps-menu update-apps-menu)
- )
\ No newline at end of file
+ )
diff --git a/man/news.texi b/man/news.texi
index 0172ff3..ac9203f 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -67,6 +67,8 @@ The @code{class} and @code{onfocused} parameters are now keys, so pass them as
#:class ''value'' or #:onfocused ''value''. Check @file{jump-or-exec.jl} for
more detailed examples.
+ item Apps-menu options @code{apps-menu-show-all} is deleted. See below for more.
+
@item User option @code{focus-ignore-pointer-events} is deleted. [Teika kazura] *
In fact, it's for internal use, and should not have been a user option. Use your favorite focus mode instead.
@@ -143,7 +145,7 @@ configurator ``Edge Actions'' group. Options must be easy to
understand.
``Hot-spot'' lets you assign an action to each screen-edge and
--corner. An action has to be a function, and can be set in
+-corner. An action has to be a lisp function, and can be set in
@file{~/.sawfish/rc}, like this:
@lisp
@@ -216,6 +218,15 @@ more.
When a lot of windows are open, they should now be more responsive.
+ item Application menu is fully customizable [Matthew Love]
+
+With the new option @code{apps-menu-filter}, you can fully customize
+the application menu. For the full description, see @xref{Applications
+Menu}.
+
+It replaces former options like @code{apps-menu-show-all} or
+ code{apps-menu-ignore-no-display}
+
@item Per-window animation mode [Teika kazura]
From the configurator ``Window Rules'' you can set the animation
@@ -442,7 +453,8 @@ Applications menu now looks more like that of GNOME / KDE / XFCE if
one is running. (further improvements are planned)
The user option @code{apps-menu-ignore-no-display} is now gone
-and replaced by @code{apps-menu-show-all}.
+and replaced by @code{apps-menu-show-all}. [Note: After Sawfish-1.8.0,
+this option is superseded by @code{apps-menu-filter}.]
If @code{apps-menu-show-all} is @code{nil} (default), the menu
looks much like that of GNOME / KDE / Xfce, by hiding some
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 42ea5dd..3f4c2d9 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -4998,7 +4998,7 @@ Note: this is just an example, not all functions in
( defvar-setq top-right-corner-function
( lambda () ( pager-unhide ) ) )
-( defvar-setq bottom-right-corner-function
+( defvar-setq bottom-right-corner-function
( lambda () ( show-desktop ) ) )
( defvar-setq bottom-left-corner-function
@@ -5358,12 +5358,16 @@ You can modify menus. @xref{Popup Definitions}.
@cindex Menus, applications
The applications menu lets you invoke installed applications. Sawfish
-generates applications menu from @file{*.desktop} files at Sawfish startup.
+generates applications menu from @file{*.desktop} files (usually found
+in @file{/usr/share/applications/}) at Sawfish startup.
+
+Functions in this section are defined in the module
+ code{sawfish wm ext apps-menu}
@menu
* Applications Menu Variables::
* Applications Menu Functions::
-* Applications Menu Filtering::
+* Desktop File Processing::
@end menu
@node Applications Menu Variables, Applications Menu Functions, Applications Menu, Applications Menu
@@ -5373,37 +5377,49 @@ generates applications menu from @file{*.desktop} files at Sawfish startup.
@defvar apps-menu-autogen
If non-nil, the applications menu is automatically generated from
- code{user-apps-menu} and @file{*.desktop} files, and stored in the
-variable @code{apps-menu}.
-Default is @code{t}.
+the variable @code{user-apps-menu} and @file{*.desktop} files, and
+stored in the variable @code{apps-menu}. Default is @code{t}.
If you set the applications menu manually to the variable
@code{apps-menu}, then it won't happen anyway.
@end defvar
+ defvar desktop-cat-alist
+Defines categorization of applications. For example, if a
+ file{* desktop} file's category has an entry ``X-Desktop'', it'll be
+classified as ``Desktop'' by Sawfish default.
+
+If another option @code{apps-menu-associate-categories} is set to nil,
+then the original value defined in @file{*.desktop} is respected.
+
+If you want to customize this variable, see the file
+ file{lisp/sawfish/wm/ext/apps-menu.jl} for the default value.
+ end defvar
+
@defvar apps-menu-associate-categories
-Associate desktop entry categories with the category-master-list.
-Default is @code{t}.
+See the above. Default is @code{t}.
@end defvar
@defvar apps-menu-filter
-The filter to use while generating the @code{apps-menu}. The default filters
-include @code{fdo-toplevel-filter} @code{fdo-nodisplay-filter} @code{fdo-hidden-filter}
- code{fdo-onlyshowin-filter} and @code{fdo-notshowin-filter}. Can also be set with
- code{'default} or @code{'some}, both of which are combinations of the default filters,
- code{'default} uses them all and @code{'some} only uses @code{fdo-notshowin-filter} and
- code{fdo-onlyshowin-filter} This can be set to @code{'nil} or @code{'()} to perform no
-filtering on the @code{apps-menu}.
-
-Also, an arbitrary filter (or combination of filters) can be defined by the user. Set this
-variable to the name of the filter, or a lambda expression, and it will be used as the
- code{apps-menu} filter.
-Default is @code{'default}.
+The filter to use while generating the @code{apps-menu}. For the details,
+see @xref{Desktop File Processing}.
+
+It can be a symbol @code{default}, @code{some}, or a function.
+
+The @code{default} filters include @code{fdo-toplevel-filter}
+ code{fdo-nodisplay-filter} @code{fdo-hidden-filter}
+ code{fdo-onlyshowin-filter} and @code{fdo-notshowin-filter}. This is
+the default value.
+
+The @code{some} filter only uses @code{fdo-notshowin-filter} and
+ code{fdo-onlyshowin-filter}
+
+Or if it is set to nil, no filtering is done.
@end defvar
@defvar desktop-directory
List of directories to look for *.desktop files. Default is
- code{'("/usr/share/applications")}.
+ code{("/usr/share/applications")}.
@end defvar
@defvar kde-desktop-directories
@@ -5411,13 +5427,13 @@ KDE specific directories where *.desktop files are stored.
@end defvar
@defvar apps-menu-alphabetize
-Sort the generated Applications menu alphabetically.
+Sort the generated applications menu alphabetically.
Defaults is @code{t}.
@end defvar
@defvar apps-menu-lang
Human language for applications menu generation, in
-string, like ``en''. Default is set from the locale.
+string, like ``en'' for English. Default is set from the locale.
@end defvar
You can prepend anything to the applications menu, by setting the
@@ -5440,9 +5456,11 @@ If you set value to @code{apps-menu}, Sawfish doesn't generate
applications menu from @file{*.desktop} files.
@defvar apps-menu
-The variable containing the definition of the applications menu. If
-you set this, it is exclusively used, and Sawfish doesn't generate
-its applications menu.
+The variable containing the definition of the applications menu. By default,
+Sawfish automatically sets this.
+
+If you set this variable manually, it is exclusively used, and Sawfish
+doesn't generate its applications menu.
@end defvar
@defvar user-apps-menu
@@ -5450,7 +5468,7 @@ Your own applications menu entries. In the applications menu, this is
followed by auto generated applications menu.
@end defvar
- node Applications Menu Functions, Applications Menu Filtering, Applications Menu Variables, Applications Menu
+ node Applications Menu Functions, Desktop File Processing, Applications Menu Variables, Applications Menu
@subsection Applications Menu Functions
@cindex Applications menu functions
@cindex Functions, applications menu
@@ -5469,142 +5487,150 @@ Return the applications menu (a list), generated from @file{*.desktop}
files which can be set to @code{apps-menu}.
@end defun
- defun parse-fdo-file
-Parse a `*.desktop' file list.
+Here're functions to process each desktop file. See also the next
+section. (@pxref{Desktop File Processing})
+
+ defun parse-fdo-file file
+Parse an *.desktop file @var{file} list.
Returns @code{(group1 (key1 . value1) ... group2 (keyA . valueA) ...)}
@end defun
@defun fdo-filter-record fdo-list filter
-Return the result of @code{filter} which can be a pre-set filter,
-such as @code{default} or @code{some} or it can be a pre-defined function of
-your choosing, which should either return a @code{fdo-list} or @code{'()}.
-If @code{filter} is not defined, will return the input @code{fdo-list}.
-This can be useful for testing filters.
+Let @var{filter} process a desktop file entry @var{fdo-list}, and
+return the result.
+
+If @var{filter} is a function, it's executed with the argument
+ var{fdo-list} If it's a symbol @code{default} or @code{some}, then
+ code{fdo-default-filter} or @code{fdo-some-filter} is exectuted,
+respectively. If @var{filter} is not defined, will return the input
+ code{fdo-list}
+
+This can be useful for testing filters, and is also used internally.
@end defun
- node Applications Menu Filtering, , Applications Menu Functions, Applications Menu
- subsection Applications Menu Filtering
+ node Desktop File Processing, , Applications Menu Functions, Applications Menu
+ subsection Desktop File Processing
@cindex Applications menu filtering
@cindex Filtering, applications menu
-While building the applications menu, sawfish sends a desktop menu
-entry through a number of so-called filters. These filters perform
-various funtions on the desktop file entry, which is defined as a
-list.
+In this section it is shown how Sawfish processes desktop file entries
+while building the applications menu. Each entry passes through many
+ dfn{filters}, and they're what you may want to customize.
-Here is an example of the desktop file entry using the
+Desktop file entries are expressed as a list. Here is an example of
@file{emacs.desktop} file before any filters are performed:
@lisp
-(``Desktop Entry''
- (``Name'' . ``Emacs Text Editor'')
- (``Name[de]'' . ``Emacs Texteditor'')
- (``GenericName'' . ``Text Editor'')
- (``Comment'' . ``Edit text'')
- (``Exec'' . ``emacs %f'')
- (``Icon'' . ``emacs-icon'')
- (``Type'' . ``Application'')
- (``Terminal'' . ``false'')
- (``Categories'' . ``Development;TextEditor;'')
- (``StartupWMClass'' . ``Emacs''))
+("Desktop Entry"
+ ("Name" . "Emacs Text Editor")
+ ("Name[de]" . "Emacs Texteditor")
+ ("GenericName" . "Text Editor")
+ ("Comment" . "Edit text")
+ ("Exec" . "emacs %f")
+ ("Icon" . "emacs-icon")
+ ("Type" . "Application")
+ ("Terminal" . "false")
+ ("Categories" . "Development;TextEditor;")
+ ("StartupWMClass" . "Emacs"))
@end lisp
-And here is the same example after the initial filters are
-performed, one of the first filters performed on the desktop
-entry list is a 'split filter, which splits the entry into
-multiple entries based on the number of categories that are
-included:
+It then gets split into two lists. The original ``Categories'' key
+contains several values, and each of new entries has ``Category'' key
+which contains only one of the original categories.
@lisp
-(``Desktop Entry''
- (``Name'' . ``Emacs Text Editor'')
- (``Name[de]'' . ``Emacs Texteditor'')
- (``GenericName'' . ``Text Editor'')
- (``Comment'' . ``Edit text'')
- (``Exec'' . ``emacs %f'')
- (``Icon'' . ``emacs-icon'')
- (``Type'' . ``Application'')
- (``Terminal'' . ``false'')
- (``Categories'' . ``Development;TextEditor;'')
- (``Cateogry'' . ``Development'')
- (``StartupWMClass'' . ``Emacs''))
-
-(``Desktop Entry''
- (``Name'' . ``Emacs Text Editor'')
- (``Name[de]'' . ``Emacs Texteditor'')
- (``GenericName'' . ``Text Editor'')
- (``Comment'' . ``Edit text'')
- (``Exec'' . ``emacs %f'')
- (``Icon'' . ``emacs-icon'')
- (``Type'' . ``Application'')
- (``Terminal'' . ``false'')
- (``Categories'' . ``Development;TextEditor;'')
- (``Cateogry'' . ``TextEditor'')
- (``StartupWMClass'' . ``Emacs''))
+("Desktop Entry"
+ ("Name" . "Emacs Text Editor")
+ ("Name[de]" . "Emacs Texteditor")
+ ("GenericName" . "Text Editor")
+ ("Comment" . "Edit text")
+ ("Exec" . "emacs %f")
+ ("Icon" . "emacs-icon")
+ ("Type" . "Application")
+ ("Terminal" . "false")
+ ("Categories" . "Development;TextEditor;")
+ ("Cateogry" . "Development") ; Look here
+ ("StartupWMClass" . "Emacs"))
+
+("Desktop Entry"
+ ("Name" . "Emacs Text Editor")
+ ("Name[de]" . "Emacs Texteditor")
+ ("GenericName" . "Text Editor")
+ ("Comment" . "Edit text")
+ ("Exec" . "emacs %f")
+ ("Icon" . "emacs-icon")
+ ("Type" . "Application")
+ ("Terminal" . "false")
+ ("Categories" . "Development;TextEditor;")
+ ("Cateogry" . "TextEditor") ; Look here
+ ("StartupWMClass" . "Emacs"))
@end lisp
@noindent
-This is the entry list format that is used in all of the later filters.
-All filtering functions should accept such an entry list as it's argument,
-and all filtering functions should either return @code{'()} or an entry list.
+This is the entry list format that is used in all of the later filters.
+All filtering functions should accept such an entry list as its argument,
+and all filtering functions should either return nil or an entry list.
If @code{fdo-associate-categories} is @code{t} then the ``Category'' key will be
changed to the main category that will eventually show up in the @code{apps-menu}.
-The keys that are used by the Applications Menu are currently,
+The keys that are used by the applications menu are currently,
@itemize @bullet
@item Name([])
-The @code{Name} key in the desktop entry list specifies the name to be used
-in the top-level of the Applications Menu. If @code{apps-menu-lang} coincides
-with one of the Name[lang] keys in the entry list, then that will be the name used.
+The name to be displayed in the applications menu. If
+ code{apps-menu-lang} or the locale coincides with one of the
+Name[lang] keys in the entry list, then that will be the name used.
+
@item Exec
-The @code{Exec} key in the desktop entry list specifies the command to be run
-when the entry is called.
+The command to be run when the entry is called.
+
@item Terminal
-The @code{Terminal} key in the desktop entry list specifies whether or not to run
-the @code{Exec} value inside of a terminal or not, this will use the default terminal.
+Whether or not to run the @code{Exec} value inside of a terminal or
+not. If it's true, the terminal specified by @code{xterm-program} is
+used.
+
@item Category
-The @code{Category} key in the desktop entry list specifies which top-level category
-to place the entry in.
+Which top-level category to place the entry in.
+
@item Hidden
-The @code{Hidden} key in the desktop entry list specifies whether or not the entry
-should be hidden by default.
+Whether or not the entry should be hidden by default.
+
@item NoDisplay
-The @code{NoDisplay} key in the desktop entry list specifies whether or not the entry
-should be displayed by default.
+Whether or not the entry should be displayed by default.
+
@item NotShowIn
-The @code{NotShowIn} key in the desktop entry list, will determine if an item should
-not be shown by checking the current desktop enviroment against the value of this key.
+If an item should not be shown by checking the current desktop
+enviroment against the value of this key.
+
@item OnlyShowIn
-The @code{OnlyShowIn} key in the desktop entry list, will determine if an item should
-be shown by checking the current desktop enviroment against the value of this key.
+If an item should be shown by checking the current desktop enviroment
+against the value of this key.
@end itemize
- noindent
-The filters can either be pre-defined filters, user-defined functions or a lambda
-expression, a user-defined function would likely look like one of the default filters
-described below.
-
- noindent
-Filter examples
+ subsubheading Filters
+Filters are functions, either pre-defined or user-defined, which take
+one argument, a desktop file entry. You can set your filter to the
+ code{apps-menu-filter} variable.
- noindent
-A lambda expression, this example will move emacs to the 'util category:
+Here we show an example user-defined filter, and all pre-defined
+filters, which are also available to user codes.
@lisp
-(setq apps-menu-filter
+;; This will move emacs to the ``util'' category, in addition to the
+;; operations done by default filter.
+(setq apps-menu-filter
(lambda (ent)
(let ((ent (fdo-default-filter ent)))
(when ent
- (cond ((string-match ``[Ee]macs'' (cdr (assoc "Name" ent)) nil t)
- (rplacd (assoc ``Category'' ent) ``util'')))
+ (cond ((string-match "[Ee]macs" (cdr (assoc "Name" ent)) nil t)
+ (rplacd (assoc "Category" ent) "util")))
ent))))
@end lisp
@@ -5613,54 +5639,55 @@ The pre-defined filters:
@lisp
(define (fdo-nodisplay-filter fdol)
- ``Return the desktop-file-list if NoDisplay is False, or if NoDisplay is
-not present in the desktop-file-list''
- (if (assoc ``NoDisplay'' fdol)
- (if (string-match ``[Ff]'' (cdr (assoc ``NoDisplay'' fdol)))
+ "Return the desktop-file-list if NoDisplay is False, or if NoDisplay is
+not present in the desktop-file-list"
+ (if (assoc "NoDisplay" fdol)
+ ;; [Ff] means match to "false"
+ (if (string-match "[Ff]" (cdr (assoc "NoDisplay" fdol)))
fdol)
fdol))
(define (fdo-hidden-filter fdol)
- ``Return the desktop-file-list if Hidden is False, or if Hidden is
-not present in the desktop-file-list''
+ "Return the desktop-file-list if Hidden is False, or if Hidden is
+not present in the desktop-file-list"
(if (assoc "Hidden" fdol)
- (if (string-match ``[Ff]'' (string-downcase (cdr (assoc ``OnlyShowIn'' fdol))))
+ (if (string-match "[Ff]" (string-downcase (cdr (assoc "OnlyShowIn" fdol))))
fdol)
fdol))
(define (fdo-onlyshowin-filter fdol)
- ``Return the desktop-file-list if OnlyShowIn matches `desktop-environment',
-or if OnlyShowIn is not present in the desktop-file-list''
- (if (assoc ``OnlyShowIn'' fdol)
- (if (string-match desktop-environment (string-downcase (cdr (assoc ``OnlyShowIn'' fdol))))
+ "Return the desktop-file-list if OnlyShowIn matches `desktop-environment',
+or if OnlyShowIn is not present in the desktop-file-list"
+ (if (assoc "OnlyShowIn" fdol)
+ (if (string-match desktop-environment (string-downcase (cdr (assoc "OnlyShowIn" fdol))))
fdol)
fdol))
(define (fdo-notshowin-filter fdol)
- ``Return the desktop-file-list if NotShowIn does not match `desktop-environment',
-or if NotShowIn is not present in the desktop-file-list''
- (if (assoc ``NotShowIn'' fdol)
- (if (not (string-match desktop-environment (string-downcase (cdr (assoc ``NotShowIn'' fdol)))))
+ "Return the desktop-file-list if NotShowIn does not match `desktop-environment',
+or if NotShowIn is not present in the desktop-file-list"
+ (if (assoc "NotShowIn" fdol)
+ (if (not (string-match desktop-environment (string-downcase (cdr (assoc "NotShowIn" fdol)))))
fdol)
fdol))
(define (fdo-associate-categories-filter fdol)
- ``If `apps-menu-associate-categories' is true, filter the
-desktop-entry through `fdo-associate-categories'.''
+ "If `apps-menu-associate-categories' is true, filter the
+desktop-entry through `fdo-associate-categories'."
(when fdol
(if apps-menu-associate-categories
(associate-categories fdol)
fdol)))
(define (fdo-toplevel-filter fdol)
- ``Return the desktop-file-list if the `Category' is of the
-Top-Level variety.''
+ "Return the desktop-file-list if the `Category' is of the
+Top-Level variety."
(when fdol
- (if (not (equal ``Top-Level'' (cdr (assoc ``Category'' fdol))))
+ (if (not (equal "Top-Level" (cdr (assoc "Category" fdol))))
fdol)))
(define (fdo-default-filter fdol)
- ``The default fdo-filter, combines the above.''
+ "The default fdo-filter, combines the above."
(fdo-toplevel-filter
(fdo-hidden-filter
(fdo-notshowin-filter
@@ -5697,7 +5724,7 @@ The second element specifies the action to take. Possible choices are:
@table @asis
@item Command
-If it's a command name (a symbol), then that command is invoked.
+If it's a command name (a symbol), then that command is invoked.
In the window operation menu, if that command takes a window as the
argument, it's passed.
@@ -7104,7 +7131,7 @@ the @code{PATH} environmental variable. Example:
@defun quit
@defunx restart
-Quits and restart Sawfish.
+Quits and restart Sawfish.
Restart does exec (3), replacing the current process. All command line
arguments are used again, except that session management related ones
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
