<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
<title>The ketchup message map library</title>
<meta name="author" content="MB" />
<style type="text/css">

@import "doc/default.css";
@import "doc/private.css";

</style>
</head>
<body>
<div class="document" id="the-ketchup-message-map-library">
<h1 class="title">The ketchup message map library</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>MB</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:mb2act&#64;yahoo.co.jp">mb2act&#64;yahoo.co.jp</a></td></tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">Distributed under the <a class="reference" href="http://opensource.org/licenses/cpl.php">Common Public License 1.0</a></td>
</tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.995</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#preface" id="id2" name="id2">Preface</a></li>
<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>
<li><a class="reference" href="#requirements" id="id4" name="id4">Requirements</a></li>
<li><a class="reference" href="#quick-start" id="id5" name="id5">Quick Start</a></li>
<li><a class="reference" href="#basic-concepts" id="id6" name="id6">Basic Concepts</a><ul>
<li><a class="reference" href="#metafunction" id="id7" name="id7">Metafunction</a></li>
<li><a class="reference" href="#message-processor" id="id8" name="id8">Message Processor</a></li>
<li><a class="reference" href="#message-map" id="id9" name="id9">Message Map</a></li>
<li><a class="reference" href="#derived" id="id10" name="id10">Derived</a></li>
<li><a class="reference" href="#chain-class" id="id11" name="id11">Chain Class</a></li>
<li><a class="reference" href="#entry" id="id12" name="id12">Entry</a></li>
<li><a class="reference" href="#id" id="id13" name="id13">id</a></li>
<li><a class="reference" href="#func" id="id14" name="id14">func</a></li>
</ul>
</li>
<li><a class="reference" href="#predefined-entry-wrappers" id="id15" name="id15">Predefined Entry Wrappers</a><ul>
<li><a class="reference" href="#message-handler" id="id16" name="id16">message_handler</a></li>
<li><a class="reference" href="#sequence" id="id17" name="id17">sequence</a></li>
<li><a class="reference" href="#chain-msg-map" id="id18" name="id18">chain_msg_map</a></li>
<li><a class="reference" href="#and" id="id19" name="id19">and...</a></li>
</ul>
</li>
<li><a class="reference" href="#cracked-handlers" id="id20" name="id20">Cracked Handlers</a></li>
<li><a class="reference" href="#mfc-update-command-ui" id="id21" name="id21">MFC Update Command UI</a></li>
<li><a class="reference" href="#compatibility" id="id22" name="id22">Compatibility</a></li>
<li><a class="reference" href="#points-of-interest" id="id23" name="id23">Points of Interest</a></li>
<li><a class="reference" href="#references" id="id24" name="id24">References</a></li>
<li><a class="reference" href="#release-notes" id="id25" name="id25">Release Notes</a></li>
</ul>
</div>
<div class="section" id="preface">
<h1><a class="toc-backref" href="#id2" name="preface">Preface</a></h1>
<p>Four yeas ago, I made a program.
Everything <a class="reference" href="http://wtl.sourceforge.net/">WTL</a> originally had was useless except win32 thin wrappers.
As CUpdateUI was the one of them, I made the replacement by macros.
Later, I read the book, <a class="reference" href="http://www.boost-consulting.com/metaprogramming-book.html">C++ Template Metaprogramming</a>, 
and I was inspired by the sample code, the finite state machine.
That could remove the marcos and the result was named ketchup, 
intended to replace BEGIN_MSG_MAP of ATL/<a class="reference" href="http://wtl.sourceforge.net/">WTL</a>.</p>
<p>In time, the experience of making <a class="reference" href="http://p-stade.sourceforge.net/biscuit/index.html">biscuit</a> gave me the way of avoiding compile-time crashes.
Now that <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> is the type-safe synonym of BEGIN_MSG_MAP.</p>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id3" name="introduction">Introduction</a></h1>
<p><a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> is a message map generator implemented using <em>class templates</em>.
The templates allow us to write type-safe BEGIN_MSG_MAP.</p>
<p>A simple BEGIN_MSG_MAP macro snippet:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\introduction_0.ipp
</pre>
<p>is approximated using <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a>'s facilities as seen in this code snippet:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\introduction_1.ipp
</pre>
</div>
<div class="section" id="requirements">
<h1><a class="toc-backref" href="#id4" name="requirements">Requirements</a></h1>
<ul class="simple">
<li>Microsoft Visual C++ .NET Version 7.1</li>
<li><a class="reference" href="http://wtl.sourceforge.net/">WTL 7.5</a></li>
<li><a class="reference" href="http://www.boost.org/">Boost C++ Libraries</a> (<a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> uses only their headers)</li>
</ul>
</div>
<div class="section" id="quick-start">
<h1><a class="toc-backref" href="#id5" name="quick-start">Quick Start</a></h1>
<ol class="arabic">
<li><p class="first">Include headers:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\quick_start_0.ipp
</pre>
</li>
<li><p class="first">Define message handlers as you did:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\quick_start_1.ipp
</pre>
</li>
<li><p class="first">Define your <a class="reference" href="#message-map">message map</a>:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\quick_start_2.ipp
</pre>
</li>
<li><p class="first">Finally, override CMessageMap::ProcessWindowMessage as BEGIN_MSG_MAP insidiously did, using <strong>ketchup::process_window_message</strong>:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\quick_start_3.ipp
</pre>
</li>
</ol>
<p>Bear in mind that declarations of message handlers should be placed before the <a class="reference" href="#entry">entry</a>, 
and the <a class="reference" href="#entry">entry</a> should be placed before ProcessWindowMessage. An <a class="reference" href="#entry">entry</a> is not a macro but a type.
<em>C++ Standard</em> doesn't allow you to abbreviate the syntax of <em>member function pointers</em>.</p>
</div>
<div class="section" id="basic-concepts">
<h1><a class="toc-backref" href="#id6" name="basic-concepts">Basic Concepts</a></h1>
<div class="section" id="metafunction">
<h2><a class="toc-backref" href="#id7" name="metafunction">Metafunction</a></h2>
<p>A <a class="reference" href="#metafunction">metafunction</a> is a <em>class</em> or a <em>class template</em> that represents a function invocable at compile-time.
Further documents are available at <a class="reference" href="http://www.boost.org/libs/mpl/doc/refmanual/metafunction.html">Boost.MPL</a>.</p>
</div>
<div class="section" id="message-processor">
<h2><a class="toc-backref" href="#id8" name="message-processor">Message Processor</a></h2>
<p>A <a class="reference" href="#message-processor">message processor</a> is any type that has the <em>member function</em>, whether <em>virtual</em> or not:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\basic_concepts_message_processor.ipp
</pre>
<p>The return value is TRUE if the message is fully handled; otherwise, it is FALSE.
This is the concept from ATL.</p>
</div>
<div class="section" id="message-map">
<h2><a class="toc-backref" href="#id9" name="message-map">Message Map</a></h2>
<p>A <a class="reference" href="#message-map">message map</a> is any type that is a nullary <a class="reference" href="#metafunction">metafunction</a> which returns an <a class="reference" href="#entry">entry</a>.</p>
</div>
<div class="section" id="derived">
<h2><a class="toc-backref" href="#id10" name="derived">Derived</a></h2>
<p>A <a class="reference" href="#derived">derived</a> is any type of object that is passed to <strong>ketchup::process_window_message</strong> as the first argument.
This name is somewhat historical.</p>
</div>
<div class="section" id="chain-class">
<h2><a class="toc-backref" href="#id11" name="chain-class">Chain Class</a></h2>
<p>A <a class="reference" href="#chain-class">chain class</a> is any <a class="reference" href="#message-processor">message processor</a> from which a <a class="reference" href="#derived">derived</a> is <em>derived</em>.
This concept also comes from ATL.</p>
</div>
<div class="section" id="entry">
<h2><a class="toc-backref" href="#id12" name="entry">Entry</a></h2>
<p>An <a class="reference" href="#entry">entry</a> is any type that has the <em>static member function</em>:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\basic_concepts_entry.ipp
</pre>
</div>
<div class="section" id="id">
<h2><a class="toc-backref" href="#id13" name="id">id</a></h2>
<p>An <a class="reference" href="#id">id</a> is any <em>static constant</em> of a <em>window message id</em> or <em>command id</em>.</p>
</div>
<div class="section" id="func">
<h2><a class="toc-backref" href="#id14" name="func">func</a></h2>
<p>A <a class="reference" href="#func">func</a> is any <em>member function</em> of a <a class="reference" href="#derived">derived</a>.</p>
</div>
</div>
<div class="section" id="predefined-entry-wrappers">
<h1><a class="toc-backref" href="#id15" name="predefined-entry-wrappers">Predefined Entry Wrappers</a></h1>
<p>All the entries and wrappers are in the <em>scope</em> of <strong>ketchup::entry_set&lt;derived&gt;</strong>, which
defines a nested <strong>_</strong> type that refers to the <a class="reference" href="#derived">derived</a>.</p>
<div class="section" id="message-handler">
<h2><a class="toc-backref" href="#id16" name="message-handler">message_handler</a></h2>
<p><a class="reference" href="#message-handler">message_handler</a> makes an <a class="reference" href="#entry">entry</a> of <em>message handler</em> from <a class="reference" href="#id">id</a> and <a class="reference" href="#func">func</a>:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\predefined_entry_wrappers_message_handler.ipp
</pre>
</div>
<div class="section" id="sequence">
<h2><a class="toc-backref" href="#id17" name="sequence">sequence</a></h2>
<p><a class="reference" href="#sequence">sequence</a> makes an <a class="reference" href="#entry">entry</a> from entries.
The maximum size of <em>template argument</em> arity is thirty.
If the size of your entries comes greater than thirty,
you can chain the entries. Keep in mind that
the <a class="reference" href="#entry">entry</a> made by <a class="reference" href="#sequence">sequence</a> is also an <a class="reference" href="#entry">entry</a>:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\predefined_entry_wrappers_sequence.ipp
</pre>
</div>
<div class="section" id="chain-msg-map">
<h2><a class="toc-backref" href="#id18" name="chain-msg-map">chain_msg_map</a></h2>
<p><a class="reference" href="#chain-msg-map">chain_msg_map</a> makes an <a class="reference" href="#entry">entry</a> from a <a class="reference" href="#chain-class">chain class</a>.</p>
</div>
<div class="section" id="and">
<h2><a class="toc-backref" href="#id19" name="and">and...</a></h2>
<p><a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> has every synonym of the BEGIN_MSG_MAP macro.</p>
</div>
</div>
<div class="section" id="cracked-handlers">
<h1><a class="toc-backref" href="#id20" name="cracked-handlers">Cracked Handlers</a></h1>
<p><a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> supports cracked handlers of WTL:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\cracked_handlers.ipp
</pre>
<p>SetMsgHandled of WTL was rejected for <em>transparency</em>. 
Instead of that, you can refer using <a class="reference" href="#entry">entry</a>.
By referring at compile-time using <a class="reference" href="#entry">entry</a>, program size becomes a little smaller. 
If you want to decide whether or not to handle a <em>message</em> at runtime, 
you must use <strong>message_handler</strong>.</p>
</div>
<div class="section" id="mfc-update-command-ui">
<h1><a class="toc-backref" href="#id21" name="mfc-update-command-ui">MFC Update Command UI</a></h1>
<p><a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> supports Updating Command UI mechanism of MFC and the limited automatic-disable:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\mfc_update_command_ui.ipp
</pre>
<p>This is a replacement for CUpdateUI of WTL. 
<strong>cmd_ui_update_menu</strong> generates a <strong>ketchup::cmd_ui</strong> object from WM_INITMENUPOPUP.
<strong>cmd_ui_enable_if_handled</strong> enables a <strong>ketchup::cmd_ui</strong> object if it is handled; otherwise, disables it.</p>
</div>
<div class="section" id="compatibility">
<h1><a class="toc-backref" href="#id22" name="compatibility">Compatibility</a></h1>
<p><a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> is compatible with BEGIN_MSG_MAP. <strong>KETCHUP_CHAIN_MSG</strong> does it.
You can enjoy and test <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> with no harm:</p>
<pre class="literal-block">
D:\Application\ketchup_0_90\libs\doc\detail\compatibility.ipp
</pre>
</div>
<div class="section" id="points-of-interest">
<h1><a class="toc-backref" href="#id23" name="points-of-interest">Points of Interest</a></h1>
<p>The last point is the performance. The demo is a WTL's sample,
MDIDocVw from which BEGIN_MSG_MAPs are removed (the same bug, a confusion between m_hWndToolbar 
and commandbar, also stands). The program size seems not to be a problem. VC++7.1 generates
the same size program as the original one, because ketchup's message map is almost same as
BEGIN_MSP_MAP. But VC++7.1 can't inline message handlers, unlike BEGIN_MSG_MAP.
Could this be a problem of the speed?</p>
<p>Well, <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> is based on the finite state machine of <a class="reference" href="http://www.boost-consulting.com/metaprogramming-book.html">C++ Template Metaprogramming</a>.
<a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> couldn't adopt the simple <em>CRTP</em> found at the book,
because <a class="reference" href="#message-processor">message processor</a> may be <em>base class</em> and the <em>multiple inheritance</em> makes
ambiguity, hundreds of entries. Now, <em>yet another layer of abstraction</em> of <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> is
a nested <a class="reference" href="#metafunction">metafunction</a>, <a class="reference" href="#message-map">message map</a>.
<strong>ketchup::entry_set&lt;derived&gt;</strong> seems to be <em>constants</em> that the <a class="reference" href="#metafunction">metafunction</a> can use.
By deriving from it, all the entries are hidden and live only in the scope.
<a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> favors <em>type</em> composition over <em>CRTP</em> 
as you favor object composition over class inheritance.</p>
<p>By the way, <a class="reference" href="http://p-stade.sourceforge.net/ketchup/index.html">ketchup</a> must be the first application using <a class="reference" href="http://boost-sandbox.sourceforge.net/libs/xpressive/doc/html/index.html">Boost.Xpressive</a> 
for the implementation.</p>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id24" name="references">References</a></h1>
<ul class="simple">
<li><a class="reference" href="http://www.codeproject.com/wtl/ketchup.asp">Forum at Code Project</a></li>
<li><a class="reference" href="http://p-stade.sourceforge.net/">p-stade</a></li>
<li><a class="reference" href="http://www.boost-consulting.com/metaprogramming-book.html">C++ Template Metaprogramming</a></li>
<li><a class="reference" href="http://www.boost.org/">Boost C++ Libraries</a></li>
<li><a class="reference" href="http://www.boost.org/libs/mpl/doc/">Boost.MPL</a></li>
<li><a class="reference" href="http://boost-sandbox.sourceforge.net/libs/xpressive/doc/html/index.html">Boost.Xpressive</a></li>
</ul>
</div>
<div class="section" id="release-notes">
<h1><a class="toc-backref" href="#id25" name="release-notes">Release Notes</a></h1>
<ul class="simple">
<li>23 May 2005 - version 0.910 (initial release)</li>
<li>30 May 2005 - version 0.950 (added class_trace and debugging_entry)</li>
<li>12 Jun 2005 - version 0.951 (removed debugging_entry; added empty_entry and debug_entry)</li>
<li>07 Jul 2005 - version 0.960 (major update)</li>
<li>08 Jul 2005 - version 0.970 (another major update)</li>
<li>13 Jul 2005 - version 0.980 (moved handler-entries to namespace ketchup)</li>
<li>14 Jul 2005 - version 0.990 (moved all the entries to entry_set)</li>
<li>16 Jul 2005 - version 0.995 (removed ketchup::set_msg_handled)</li>
</ul>
<p>The version 0.960 or later no longer depends on <em>MPL Sequence</em> of <a class="reference" href="http://www.boost.org/libs/mpl/doc/">Boost.MPL</a>.
Instead of that, it depends on <em>partial class template specialization</em>,
so you can see and easily debug your code.</p>
</div>
</div>
<div class="footer">
<hr class="footer" />
This document was generated by <a class="reference" href="http://docutils.sourceforge.net/index.html">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source and
syntax-highlighted using <a class="reference" href="http://p-stade.sourceforge.net/biscuit/index.html">biscuit</a>.
</div>
</body>
</html>
