From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id INN5OMAxTGIDRwEAgWs5BA (envelope-from ) for ; Tue, 05 Apr 2022 14:10:40 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id SMLtNMAxTGIbOgAAauVa8A (envelope-from ) for ; Tue, 05 Apr 2022 14:10:40 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 46F7C8694 for ; Tue, 5 Apr 2022 14:10:40 +0200 (CEST) Received: from localhost ([::1]:44578 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nbi19-0003RW-GF for larch@yhetil.org; Tue, 05 Apr 2022 08:10:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54670) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nbhzS-00030i-NZ for emacs-orgmode@gnu.org; Tue, 05 Apr 2022 08:08:55 -0400 Received: from mail-4318.protonmail.ch ([185.70.43.18]:58793) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nbhzP-0003PA-Mq for emacs-orgmode@gnu.org; Tue, 05 Apr 2022 08:08:53 -0400 Date: Tue, 05 Apr 2022 12:08:37 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com; s=protonmail; t=1649160527; bh=9B9RuSmAj9gV3AJlA2DxFc3fQbpJeIlQKehoKYOq8SE=; h=Date:To:From:Cc:Reply-To:Subject:Message-ID:From:To:Cc:Date: Subject:Reply-To:Feedback-ID:Message-ID; b=wmZ1U6l50aC1nCru1RLdlmaTLKXggW6UWqVy0SKTrxTpC4kc9GmKc+3saEVvUaGDx 4hIWG7FtlEhSwWQbHcIPaDEZg2YHasAjYhgokQadULPG9aHQ3yHKoieYeBPhBi1rvQ a2nVQ5vYI2XorZRHhYxzT7mtYneqEvSOIvXUN3V71THr/uFr2xIzlPL1YEDSEux7Sk olMFK/i765G9EY9uSFpumhhU6ERHj73+CfVNsHAGhBRShGL5m//wAjG1hIxSRUjLm6 pFmsct8wsZXWmR+EBU1Wb0GSipiklM3AfeS68SNTYT1HA2WksleyqGrTblObsndwIo naoXvfaiE2rIA== To: emacs-orgmode@gnu.org From: thecashewtrader Cc: thecashewtrader Subject: [PATCH] Document custom org agenda functions Message-ID: <20220405120728.12871-1-thecashewtrader@protonmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.70.43.18; envelope-from=thecashewtrader@protonmail.com; helo=mail-4318.protonmail.ch X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: thecashewtrader Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1649160640; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=9B9RuSmAj9gV3AJlA2DxFc3fQbpJeIlQKehoKYOq8SE=; b=k7vGCVD/+VDBed3vLGF1jDNHL0z6Vy9y6S+SzZMPoEjXSBGKznl0TkMJr0uqEm2E0N8Qdo FbpiJ04QOiPnzzdfcNY7UXK5lGHPECO71OHEkVk4FFYVOSVknQZYS2wvjv3SDlblo1OiQt Qww94KWG7x5jrHlhuozrxHE83lGy2KQfiSKvhc6K5P3YootrtWwwPRe55sfsGaabxOvtfm TKgH8kEmaMzpBdXFKk9lNu+r6hFIRhfIuBEYmBooP2vFA/rXOCgfNMNnsSmNaTrtVjZTvE tlDxFVqzHjnwmkKBDRaraVvBrO9egbESHg3Vn39kb6y/XW0RL+wIQRejFJ86Aw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1649160640; a=rsa-sha256; cv=none; b=P0yFjN+BiLeAYBEKzujWAJc0oEK+lfm873vuKND4llMlAfIsOq45bskbJS0PX1eB/ce87j Et7hPdqpCT7getWPksKsujgBsKnE8NHsmbIhA8SgjQ5mJX+v03n5hejTTTwga8zOaS350X P+cHjJBKX9A08+6USm4NN2IihoURlv1HMojgLowmqVraaWks9xOQ7/e43rRaAntwupTMBF 6y/dn41lL104+RbHLRv2IRKvDKFWPiz93Ztxi3y/ncgLk8SFJS4rghL3JQx1ymWvi3w3rd QFWwNJjh1NDhjkoKtHGvCHDJBGBIhhR7egXkT3xiB7AHjsXtQN6KJFOC1r8Gww== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=protonmail.com header.s=protonmail header.b=wmZ1U6l5; dmarc=pass (policy=quarantine) header.from=protonmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -8.37 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=protonmail.com header.s=protonmail header.b=wmZ1U6l5; dmarc=pass (policy=quarantine) header.from=protonmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 46F7C8694 X-Spam-Score: -8.37 X-Migadu-Scanner: scn0.migadu.com X-TUID: kEGg27VWWbi1 --- org-tutorials/org-custom-agenda-commands.org | 40 +++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/org-tutorials/org-custom-agenda-commands.org b/org-tutorials/o= rg-custom-agenda-commands.org index e54bcef3..5b55ebb5 100644 --- a/org-tutorials/org-custom-agenda-commands.org +++ b/org-tutorials/org-custom-agenda-commands.org @@ -64,7 +64,7 @@ command is a list consisting of the following: (optional). - 3) Type of search :: The desired agenda display/search. The options include agenda, todo, search, tags, alltodo, tags-todo, - todo-tree, tags-tree, occur-tree, or a user-defined function. + todo-tree, tags-tree, occur-tree, or a [[*User Defined Functions][use= r-defined function]]. - 4) Search term :: Depending on the type of search, this will be a TODO keyword, a tag (or property), a word, or a regular expression. @@ -372,6 +372,44 @@ deadlines and nothing else. Tip: if you want to exclude all agenda entry types, just set =3Dorg-agenda-entry-types=3D to nil. =20 +* User Defined Functions +** Function Signature +User defined functions should: + +- Optionally accept one parameter i.e. the =3Dmatch=3D variable. The Org a= genda dispatch function will call the user-defined function with one parame= ter representing the =3Dmatch=3D component from the agenda definition. In o= ther words, ~(udf/test "Hello")~ in =3Dorg-agenda-custom-commands=3D will r= esult in a function call of ~udf/test~ with an argument of =3D"Hello"=3D. + +- Prepare a buffer to write the agenda information to using ~org-agenda-pr= epare~. + +- Handle setting a unique buffer name for the cases where =3Dorg-agenda-st= icky=3D has a value of =3Dt=3D. + +- Honor the setting of =3Dorg-agenda-overriding-header=3D and insert that = text into the agenda buffer. This can be done using the macro ~org-agenda--= insert-overriding-header~. + +- Insert into the buffer the desired contents, accounting for also setting= text properties. + +- Call ~org-agenda-finalize~ and ~(setq buffer-read-only t)~ + +** Example +This is a simple function to insert notes into the Agenda. + +*NOTE: This example is not fully complete as it doesn't respect =3Dorg-age= nda-sticky=3D.* + +#+begin_src emacs-lisp + +(defun udf/org-agenda-notes (&optional arg) + (org-agenda-prepare "Notes") + (org-agenda--insert-overriding-header "Notes") + (let ((org-agenda-notes + (list "Note 1" + "Note 2" + "Note 3"))) + (dolist (note org-agenda-notes) + (insert (format "- %s\n" note)))) + (org-agenda-finalize) + (setq buffer-read-only t)) + +#+end_src + + * Other configuration ideas =20 This section is for additional ideas for configuring --=20 2.35.1