From mboxrd@z Thu Jan  1 00:00:00 1970
From: Mike McLean <mike.mclean@pobox.com>
Subject: User Defined Functions in Agenda Views
Date: Sat, 21 Sep 2013 14:18:47 -0400
Message-ID: <6F30E9CD-36ED-4281-BD6F-0D3B623393B9@pobox.com>
Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\))
Content-Type: multipart/alternative;
	boundary="Apple-Mail=_8E8014AD-0C40-4DAD-8783-BEA2CD252ED6"
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:49405)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mike.mclean@pobox.com>) id 1VNRli-00015O-UK
	for emacs-orgmode@gnu.org; Sat, 21 Sep 2013 14:19:04 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <mike.mclean@pobox.com>) id 1VNRlb-0007ju-IA
	for emacs-orgmode@gnu.org; Sat, 21 Sep 2013 14:18:58 -0400
Received: from a-pb-sasl-quonix.pobox.com ([208.72.237.25]:34385
	helo=sasl.smtp.pobox.com) by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mike.mclean@pobox.com>) id 1VNRlb-0007jR-C1
	for emacs-orgmode@gnu.org; Sat, 21 Sep 2013 14:18:51 -0400
Received: from sasl.smtp.pobox.com (unknown [127.0.0.1])
	by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id D6548D75E
	for <emacs-orgmode@gnu.org>; Sat, 21 Sep 2013 14:18:48 -0400 (EDT)
Received: from a-pb-sasl-quonix.pobox.com (unknown [127.0.0.1])
	by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTP id CDDA1D75D
	for <emacs-orgmode@gnu.org>; Sat, 21 Sep 2013 14:18:48 -0400 (EDT)
Received: from mac-mike-2013.mclean (unknown [67.190.221.110])
	(using TLSv1 with cipher AES128-SHA (128/128 bits))
	(No client certificate requested)
	by a-pb-sasl-quonix.pobox.com (Postfix) with ESMTPSA id 4473BD75C
	for <emacs-orgmode@gnu.org>; Sat, 21 Sep 2013 14:18:48 -0400 (EDT)
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-orgmode>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
To: org mode <emacs-orgmode@gnu.org>


--Apple-Mail=_8E8014AD-0C40-4DAD-8783-BEA2CD252ED6
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=windows-1252

Hello

I looked at the doc string for ~org-agenda-custom-commands~ and noticed =
that the you can use a user-defined function as a valid command type. I =
did not find anything in the documentation that describes how that =
user-defined function should work, what it should do, or how to write =
one. I looked at the code for other agenda types, such as ~tags-todo~ =
and ~occur-tree~ and have guessed at how to form one of these.

I can write documentation and samples if anyone want it (either to add =
to Org documentation or as a page on Worg), but want to ensure that I =
understand completely and correctly, first.

With that said, can those with far more knowledegble about Org code =
comment on my thoughts below.

The user defined function for an agenda view:
The Org agenda dispatch function will call a user-defined function with =
one parameter representing the ``match'' component from the agenda =
definition. In other words, ~(udf-test "Hello")~ in =
~org-agenda-custom-commands~ will result in a function call of =
~udf-test~ with an argument of "Hello".
The ~org-agenda-custom-commands~ varible does not requred a parameter =
and therefore the dispatcher does not require one. Define an =
user-defined wiht an optional argument: ~(defun udf-test (&optional =
org-match) "documentation=85" <<code>>)~
The user defined function should prepared a buffer to write the agenda =
information to using ~org-agenda-prepare~
The user defined function should handle setting a unique buffer name for =
the cases where ~org-agenda-sticky~ has a value of ~t~
Honor the setting of ~org-agenda-overriding-header~ and insert that text =
into the agenda buffer
Insert into the buffer the desired contents, accounting for also setting =
text properties (translation: =93Magic happens here=94)
Call ~org-agenda-finalize~ and ~(setq buffer-read-only t)~

Does this cover the basics?

Mike


--Apple-Mail=_8E8014AD-0C40-4DAD-8783-BEA2CD252ED6
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=windows-1252

<html><head><meta http-equiv=3D"Content-Type" content=3D"text/html =
charset=3Dwindows-1252"></head><body style=3D"word-wrap: break-word; =
-webkit-nbsp-mode: space; -webkit-line-break: after-white-space; =
"><div>Hello</div><div><br></div><div>I looked at the doc string for =
~org-agenda-custom-commands~ and noticed that the you can use a =
user-defined function as a valid command type. I did not find anything =
in the documentation that describes how that user-defined function =
should work, what it should do, or how to write one. I looked at the =
code for other agenda types, such as ~tags-todo~ and ~occur-tree~ and =
have guessed at how to form one of these.</div><div><br></div><div>I can =
write documentation and samples if anyone want it (either to add to Org =
documentation or as a page on Worg), but want to ensure that I =
understand completely and correctly, =
first.</div><div><br></div><div>With that said, can those with far more =
knowledegble about Org code comment on my thoughts =
below.</div><div><br></div><div>The user defined function for an agenda =
view:</div><div><ul><li>The Org agenda dispatch function will call a =
user-defined function with one parameter representing the ``match'' =
component from the agenda definition. In other words, ~(udf-test =
"Hello")~ in ~org-agenda-custom-commands~ will result in a function call =
of ~udf-test~ with an argument of "Hello".</li><li>The =
~org-agenda-custom-commands~ varible does not requred a parameter and =
therefore the dispatcher does not require one. Define an user-defined =
wiht an optional argument: ~(defun udf-test (&amp;optional org-match) =
"documentation=85" &lt;&lt;code&gt;&gt;)~</li><li>The user defined =
function should prepared a buffer to write the agenda information to =
using ~org-agenda-prepare~</li><li>The user defined function should =
handle setting a unique buffer name for the cases where =
~org-agenda-sticky~ has a value of ~t~</li><li>Honor the setting of =
~org-agenda-overriding-header~ and insert that text into the agenda =
buffer</li><li>Insert into the buffer the desired contents, accounting =
for also setting text properties (translation: =93Magic happens =
here=94)</li><li>Call ~org-agenda-finalize~ and ~(setq buffer-read-only =
t)~</li></ul></div><div><br></div><div>Does this cover the =
basics?</div><div><br></div><div>Mike</div><div><br></div></body></html>=

--Apple-Mail=_8E8014AD-0C40-4DAD-8783-BEA2CD252ED6--