#
# top-level minx build spec
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki for the full list of authors who have
# contributed to this project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

# Min cmake version
cmake_minimum_required(VERSION 2.8)

# Project name
project(minx)

# Build sub-projects
add_subdirectory(minxlib)
add_subdirectory(dox)

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# sh-basic-offset: 4                         #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# __init__.py -- initialization for minx module
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki for the full list of authors who have
# contributed to this project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#----------------------------- EXPORTS ---------------------------------

__all__ = ["core"]

# Pull in minx.core so that users don't have to do it explicitly
# themselves...
import core

#-----------------------------------------------------------------------

# Editor config:
#
# Local Variables:
# indent-tabs-mode: nil
# py-indent-offset: 4
# End:
#
# vim: expandtab shiftwidth=4 tabstop=4

#
# __init__.py -- initialization for minx.core module
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#----------------------------- IMPORTS ---------------------------------

# Pull in various classes from minx.core so that end-users see them as
# minx.core.wm instead of minx.core.wm.wm, minx.core.config instead of
# minx.core.config.config, and so on.
from wm import wm
from config import config

#----------------------------- EXPORTS ---------------------------------

__all__ = ["wm", "config", "hooks"]

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# config.py -- various end-user settings
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------ MODULE DOC STRING ----------------------------

"""@package minx.core.config
Settings object.

This file defines a config class that contains attributes for various
settings through which end-users can effect simple customizations.

"""

#------------------------- CLASS DEFINITION ----------------------------

class config:
    """Attributes for simple customizations.

    This class has the following attributes to allow simple
    customizations. In the list below, the parenthesized term specifies
    the type of the attribute and the term in square brackets is the
    attribute's default value.

    <h3>Focus-related Customizations</h3>

        @li <tt>active_border_color</tt> <b>(int)</b> [<em>0xFF0000</em>]:
            This attribute specifies the color of the border of the
            window with the input focus. It should be a three-byte RGB
            packed into a single integer. The easiest way to specify
            this is as a 24-bit hex number, where byte 0 is blue, byte 1
            is green, and byte 2 is red. By default, the active window's
            border color is red.
        @li <tt>inactive_border_color</tt> <b>(int)</b> [<em>0xFFFFFF</em>]:
            This attribute specifies the color of unfocused windows. By
            default, this color is white.
        @li <tt>active_border_size</tt> <b>(int)</b> [<em>1</em>]:
            This attribute specifies the size (in pixels) of the border
            of the window with the input focus.
        @li <tt>inactive_border_size</tt> <b>(int)</b> [<em>1</em>]:
            This attribute specifies the border size (in pixels) of
            inactive windows.

    <h3>Logging Configuration</h3>

        @li <tt>logger</tt> <b>(dict)</b> [<em>see below</em>]:
            This field is passed to
            <a href="http://docs.python.org/2/library/logging.config.html#logging.config.dictConfig">logging.config.dictConfig()</a>.
            The default configuration sets up a
            <a href="http://docs.python.org/2/library/logging.handlers.html#logging.NullHandler">logging.NullHandler</a>
            to suppress Minx's log messages.

            To enable logging, use either log_to_console() to send log
            messages to STDERR or log_to_file() to send them to a file.
            You can also use log_level() to configure the level of
            verbosity.

            The above three functions should be enough to configure
            logging for the most common cases. However, you can further
            customize logging by retrieving the keys of the logger dict
            and reassigning them to the desired values. The following
            paragraphs provide some details.

            <tt>logger['formatters']['minx_formatter']</tt> will get you
            a reference to the formatter for Minx's log messages. This
            formatter is itself a dict with the keys <tt>'format'</tt>
            and <tt>'datefmt'</tt>. Consult the
            <a href="http://docs.python.org/2/library/logging.config.html#logging-config-dictschema">Python logging documentation</a>
            for further details about formatters.

            <tt>logger['handlers']['minx_handler']</tt> yields Minx's
            logging handler, which is also a dict with keys
            <tt>'class'</tt> and <tt>'formatter'</tt>. As mentioned
            above, the handler's <tt>'class'</tt> is
            <tt>'logging.NullHandler'</tt>. The value of the
            <tt>'formatter'</tt> key is <tt>'minx_formatter'</tt>. You
            should reset <tt>'class'</tt> to another logging handler
            class (e.g., <tt>'logging.FileHandler'</tt>). You should
            also set other keys appropriately. Consult the Python
            logging module's documentation for more info.

            Instead of using the predefined <tt>'minx_formatter'</tt>
            and <tt>'minx_handler'</tt> keys as described above, you can
            also reset the <tt>config</tt> object's <tt>logger</tt>
            attribute to anything you want.

    <h3>Miscellaneous Settings</h3>

        @li <tt>terminal</tt> <b>(string)</b> [<em>xterm</em>]:
            This field specifies the command to use for launching a
            terminal window. Your PATH variable will be searched to find
            it; so you don't have to specify a full path. Moreover, you
            can supply command-line arguments for the terminal program
            in this setting and they will be passed as-is. Minx's
            default configuration defines a
            <a href="../wiki/hooks-list.wiki#launch_terminal>key binding</a>
            that uses the value of this setting.
        @li <tt>synchronize_xlib</tt> <b>(Boolean)</b> [<em>False</em>]:
            If set to <tt>True</tt>, Xlib calls will be synchronous;
            otherwise, the X protocol operates asynchronously.
            Synchronous mode can be useful for debugging.

    """

    # Constructor
    def __init__(self):
        """Default values for various settings.

        Instantiating this class will result in a config object with
        default values for the various settings. Clients can then assign
        different values to the desired attributes to customize Minx and
        pass the modified config object to the @ref minx.core.wm.wm "wm"
        constructor.

        """
        self.active_border_color   = 0xFF0000
        self.inactive_border_color = 0xFFFFFF
        self.active_border_size    = 1
        self.inactive_border_size  = 1

        self.logger = self._init_logger()

        self.terminal = 'xterm'
        self.synchronize_xlib = False

    # Helper to initialize logger configuration
    def _init_logger(self):
        mesg_format = ('%(asctime)s.%(msecs)03d %(levelname)-9s' +
                       '%(name)-18s%(lineno)-5s%(funcName)s\n  ' +
                       '  %(message)s')
        date_format = '%Y-%m-%d %H:%M:%S'
        formatter   = {'format' : mesg_format,
                       'datefmt': date_format}

        # Helper class to strip "minx." prefix from module name of each
        # log record (to save some space on each header line). Also:
        # line number and function name for messages from the minxlib
        # module are incorrect; so this filter removes those things from
        # log records produced by the minxlib module.
        class _minx_logging_filter:
            def filter(self, log_record):
                log_record.name = log_record.name.replace('minx.', '')
                if log_record.name.startswith('minxlib'):
                   log_record.lineno   = ''
                   log_record.funcName = ''
                return 1
        filter_ = {'()': lambda: _minx_logging_filter()}

        handler = {'class'    : 'logging.NullHandler',
                   'formatter': 'minx_formatter',
                   'filters'  : ['minx_filter']}

        logger = {'handlers': ['minx_handler']}

        return {'version'   : 1,
                'formatters': {'minx_formatter': formatter},
                'filters'   : {'minx_filter'   : filter_  },
                'handlers'  : {'minx_handler'  : handler  },
                'loggers'   : {'minx'          : logger   }}

    # Convenience function for configuring logging to console
    def log_to_console(self):
        """Send log messages to STDERR.

        This is a convenience function that allows you to avoid dealing
        directly with the <tt>config.logger</tt> attribute's complicated
        dict-of-dict-of-dict structure. Using it, you can easily
        configure Minx's log messages to be printed to STDERR.

        """
        handler = self.logger['handlers']['minx_handler']
        handler['class'] = 'logging.StreamHandler'

    # Convenience function for configuring logging to a file
    def log_to_file(self, name, mode = 'w'):
        """Send log messages to a file.

        @param name Log file's name.
        @param mode Log file open mode; default = 'w'.

        One of the most common configurations for logging is to send log
        messages to a file. This function configures the
        <tt>config.logger</tt> attribute so that log messages will be
        written to the named file. By default, the log will be
        overwritten. However, if you use the value 'a' for the
        <tt>mode</tt> parameter, log messages will be appended to the
        file.

        As described earlier, you can configure Minx's logging by
        directly manipulating the <tt>config.logger</tt> dict. However,
        since that process can be somewhat convoluted and because
        sending log messages to a file is a fairly common thing to do,
        it's easier to use this function.

        """
        handler = self.logger['handlers']['minx_handler']
        handler['class'   ] = 'logging.FileHandler'
        handler['filename'] = name
        handler['mode'    ] = mode

    # Convenience function for configuring logging level
    def log_level(self, level):
        """Set the level of logging verbosity.

        @param level The log level from the Python logging module.

        The default log level is <tt>logging.WARNING</tt>. Thus, only
        <tt>WARNING</tt>, <tt>ERROR</tt>, and <tt>CRITICAL</tt> messages
        will be printed. However, with this function, you can change the
        log level to either produce more or fewer messages.

        Consult the Python logging documentation for more details about
        logging levels.

        """
        logger  = self.logger['loggers' ]['minx']
        handler = self.logger['handlers']['minx_handler']
        logger ['level'] = level
        handler['level'] = level

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# focus_list.py -- circular, doubly linked list of top-level windows
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------ MODULE DOC STRING ----------------------------

"""@package wm.core.focus_list

This file defines the minx.core.focus_list.focus_list class, which can
be referred to simply as minx.core.focus_list.

"""

#------------------------- CLASS DEFINITION ----------------------------

class focus_list:
    """A doubly-linked circular list for keeping track of windows that
    can be focused.

    This class implements a doubly-linked circular list that is meant to
    be used by @ref minx.core.wm.wm "the window manager" for keeping
    track of the list of @ref minxlib::window "top-level windows" that
    can be focused. The head of this list will always be taken to be the
    currently focused window.

    """

    # Internal class for storing an item and references to its two
    # neighbours.
    class _node:
        def __init__(self, item):
            self._item  = item
            self._left  = None
            self._right = None

    # Constructor
    def __init__(self):
        """Create an empty list.

        """
        self._head = None

    # Adding elements to the focus list
    def add(self, item):
        """Insert an item at the beginning of the list.

        @param item The item to be added.

        This method inserts item (which can be of any type) at the
        beginning of the list, taking care to maintain circularity.

        @note We add new items to the beginning of the list because this
        is usually how we want input focus to behave: when a new window
        is created, it should acquire the input focus.

        """
        node = self._node(item) # create a new node to store item
        if self._head == None:  # list is empty
           node._left  = node
           node._right = node
        else: # list has at least one element
           tail = self._head._left
           tail._right = node
           node._left  = tail
           node._right = self._head
           self._head._left = node
        self._head = node

    # Removing items from from the focus list
    def remove(self, item):
        """Remove specified item from list.

        @param item List item to be removed.

        This method searches the list for item and, if it is present,
        removes it, taking care to maintain circularity. If item is the
        first element in the list, the second element will become the
        list's new head after the removal.

        @note To be able to find item, we need its type to support the
        equality operator. Also, if item occurs more than once, the
        first instance will be removed.

        """
        node = self._find(item)
        if node == None: # list does not contain specified item
           return        # therefore, nothing to remove
        else:
           self._remove_node(node)

    # Helper function for node removal
    def _remove_node(self, node):
        if node == self._head: # removing list's first element
           if (self._head._left  == self._head and
               self._head._right == self._head): # list has only one element
               self._head._left  = None
               self._head._right = None
               self._head        = None
           else: # removing first element when list has more than one item
               tail = self._head._left
               tail._right = self._head._right
               self._head._right._left = tail
               self._head._left  = None
               self._head._right = None
               self._head = tail._right
        else: # removing an item after the lists' first element
            node._left._right = node._right
            node._right._left = node._left
            node._left  = None
            node._right = None

    # Helper function for finding items in list
    def _find(self, item):
        if self._head == None: # list is empty
           return None         # therefore, it cannot contain item

        if self._head._item == item: # item is list's first element
           return self._head         # so let's return that

        # Look for item starting at second element of list
        node = self._head._right
        while node != self._head:
            if node._item == item: # found it!
               return node
            node = node._right # no luck yet, examine next element

        # If we get to this point, then the list does not contain item
        return None

    # Return list's first element
    def head(self):
        """Return list's first element or None if list is empty.

        """
        if self._head == None:
           return None
        return self._head._item

    def forward(self):
        """Move head to next element.

        This method is meant to allow moving the input focus from the
        current @ref minxlib::window "top-level window" to the next one
        in the @ref minx.core.wm.wm "window manager's" list of windows
        that can be focused.

        If the focus list is empty, this function does nothing.

        """
        if self._head != None:
           self._head  = self._head._right

    def backward(self):
        """Move head to previous element.

        This method is meant to allow moving the input focus from the
        current @ref minxlib::window "top-level window" to the previous
        one in the @ref minx.core.wm.wm "window manager's" list of
        windows that can be focused.

        If the focus list is empty, this function does nothing.

        """
        if self._head != None:
           self._head  = self._head._left

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

##
# @file  hooks.py
# @brief Minx's hooking infrastructure.
# @defgroup grp_minx_core_hooks Hooks Infrastructure
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------ MODULE DOC STRING ----------------------------

"""@ingroup grp_minx_core_hooks
Minx's infrastructure for defining and using hooks.

This module defines the minx.core.hooks.hooks and related classes that
implement the infrastructure for defining and triggering hook functions,
which are callbacks that Minx invokes in response to different events.
Minx uses hooks both internally (to handle events sent by the X server)
and externally (to allow end-users to customize its responses to and
also to be notified of different window manager events).

"""

#----------------------------- IMPORTS ---------------------------------

# Standard library
from heapq import heappush
import logging

#-------------------------- MODULE LOGGER ------------------------------

logger = logging.getLogger(__name__)

#------------------------- CLASS DEFINITION ----------------------------

class hooks:
    """@ingroup grp_minx_core_hooks
    Mapping arbitrary key types to callable objects.

    This class maps keys (strings, ints, whatever) to prioritized lists
    of callables (i.e., functions or function objects). After a mapping
    has been setup, clients can trigger the functions for a key.

    This class provides a general infrastructure for Minx's support for
    customization via hooks. Although we can use any (reasonable) type
    as the keys, in Minx, keys are strings that name the different hooks
    that Minx supports (e.g., 'manage_hook', 'x_create_notify', and so
    on). If you name your hooks using a non-string type, those hooks
    will be added to the map but simply be ignored.

    """

    MIN_PRIORITY = 0
    MAX_PRIORITY = 101

    # Constructor
    def __init__(self):
        """Create an empty hook map.

        @return An empty hook map.

        When a new hooks object is created, it will have no hook
        functions in it. Clients (i.e., other Minx classes and
        functions or end-user configuration code) will have to then add
        hook functions to the hook map.

        @note In general, there should be no need in end-user code to
        create a hooks object. Rather, end-users should use the hooks
        attribute of the @ref minx.core.wm.wm "main window manager object".
        Refer to the <a href="../wiki/hooks-howto.wiki">Hooks HOWTO</a>
        for more on typical usage patterns for this class.

        """
        self._hooks = {}

    # Add a new function for some key
    def add(self, k, f, p = None):
        """Add a new function for some key.

        @param k The name of the hook.
        @param f The function to be executed for k.
        @param p The function priority (must be in range [1, 100]).

        This method adds f to the (prioritized) list of functions
        corresponding to k. If f is already in the list for k, it will
        not be duplicated. Thus, you can safely call this function
        multiple times with the same hook without worrying about
        creating duplicate entries in the hook lists or needing to
        first check to avoid duplication. This is useful, for example,
        when creating window objects that add hooks for various X
        events; the same function will be passed for each window
        instance and we don't want duplicate entries of the same
        function in our hook map (because each hook should be called
        once and only once per triggering).

        Priorities should be integers in the range [1, 100]. Higher
        numbers will insert f into the beginning of the list. If the
        priority p is not supplied, it will be assigned a default
        priority. Passing a non-integral value for the parameter p will
        also result in the priority for f being set to the default
        priority.

        To add a hook at the highest priority, pass MAX_PRIORITY as the
        value of p. Similarly, to add a hook at the lowest priority, pass
        MIN_PRIORITY as the value of p. Alternatively, to add hooks at
        the highest or lowest priorities, you can pass values greater
        than hundred or less than one respectively (however, using
        MAX_PRIORITY and MIN_PRIORITY is probably clearer).

        Here is a snippet of code illustrating how to add a hook for some
        event 'foo' so that it is the highest priority hook:

        @verbatim
            wm.hooks.add('foo', my_foo_hook, wm.hooks.MAX_PRIORITY)
        @endverbatim

        In general, you should not care about the order in which hooks
        execute. That is, you should implement hook functions so that the
        final result is the same regardless of the order of their
        execution. Having said that, however, such idealism is not always
        feasible, and, depending on the specific situation, perhaps not
        even wholly desirable. Thus, if you do need to control the order
        in which your hooks execute, you should be aware that the order
        in which you add hooks can be significant, especially if you use
        MIN_PRIORITY and MAX_PRIORITY.

        For example, let's say you have two hooks A and B for some key
        "foo" and want to execute A before B and B before every other
        hook for "foo." If you add the hooks in the following order:

        @verbatim
            wm.hooks.add('foo', A, wm.hooks.MAX_PRIORITY)
            wm.hooks.add('foo', B, wm.hooks.MAX_PRIORITY)
        @endverbatim

        B will end up at a higher priority than A and will execute before
        A instead of the other way around. This is because, MIN_PRIORITY
        and MAX_PRIORITY look at the current minimum and maximum
        priorities and are not absolute values. To achieve the effect
        described above, you should first add B and then A.
        Alternatively, you could also do the following:

        @verbatim
            wm.hooks.add('foo', A, wm.hooks.MAX_PRIORITY)
            wm.hooks.add('foo', B, wm.hooks.max_priority('foo'))
        @endverbatim

        The above code will first add A at the current highest priority
        for "foo" and then add B at the same priority as A.

        @note As mentioned earlier, although you can use any
        (reasonable) type for the hook map's keys, in Minx, we use
        strings as the keys. That is, pass a string as the first
        parameter k.

        """
        if k not in self._hooks:
           self._hooks[k] = priority_queue()

        if p == None or not isinstance(p, int):
           p = self.default_priority()
        elif p < 1:
           p = self.min_priority(k)
           if p == -1:
              p = self.default_priority() - 1
           else:
              p = max(1, p - 1)
        elif p > 100:
           p = self.max_priority(k)
           if p == -1:
              p = self.default_priority() + 1
           else:
              p = min(p + 1, 100)

        if self._hooks[k].add(f, p):
           logger.info('added hook: [{}, {}, {}]'.format(k, f.__name__, p))

    # Remove all hooks for specified name
    def remove(self, k):
        """Remove all hooks for specified name.

        @param k Name of hook that is to be removed.

        This function will remove all the hooks corresponding to the
        name k.

        Please understand that this is a fairly dangerous function! It
        is intended to be used in conjunction with hooks for key
        bindings. Specifically, you can use it to remove the default key
        bindings. Using it to remove other hooks will almost certainly
        lead to trouble.

        @note As mentioned earlier, although you can use any
        (reasonable) type for the hook map's keys, in Minx, we use
        strings as the keys. That is, pass a string for the parameter k.

        """
        if k in self._hooks:
           del self._hooks[k]
           logger.info('removed {} hooks'.format(k))

    # Rename specified hook
    def rename(self, k, n):
        """Rename the specified hook.

        @param k Current name of hook to be renamed.
        @param n New hook name.

        This function will assign the name n to the hooks currently
        identified by k. If the hook map does not contain any hooks
        corresponding to k, the function will do nothing. However, if
        there are already hooks assigned to n and to k, the older hooks
        for n will be replaced by the ones for k.

        Needless to say, this is a fairly dangerous function! Use it
        only to rename the default key bindings. Renaming other hooks is
        a Very Bad Idea (TM).

        @note Both k and n should be strings. Although you can use any
        (reasonable) type as keys for the hook map, Minx convention is
        to use strings. Other key types will result in "ghost" hooks,
        i.e., hook functions that are never triggered.

        """
        if k in self._hooks:
           self._hooks[n] = self._hooks[k]
           del self._hooks[k]
           logger.info('renamed {} hooks to {}'.format(k, n))

    # Call all the functions corresponding to a key
    def trigger(self, k, *p):
        """Execute functions for a given key.

        @param  k The name of the hook whose functions we want to call.
        @param  p Parameters to be passed to the hook functions.
        @return List of hook return values.

        This method triggers all the functions corresponding to k,
        calling them in order of descending priorities. Functions that
        have the same priority will be executed in the order in which
        they were added to the hook map.

        Each function will be passed the parameters in the positional
        args tuple p. Thus, hook functions can take an arbitrary number
        of arguments. Furthermore, these hook function parameters can be
        of any type; this method doesn't care and simply passes them
        through to the hooks as-is.

        This function collects the return values of all the hook
        functions for key k in a list. Callers of this function can use
        the return values in whatever way they please. For example,
        depending on the specific hook, you may:

            @li Simply ignore the hook return values.
            @li Use only the first return value, i.e., the value
                returned by the highest-priority hook.
            @li Use the last return value (i.e., last hook executed).
            @li Use all the return values.

        If a hook wants or needs to cut short the execution of the
        remaining hooks in its chain, it can raise a short_circuit
        exception. If the hook also wants to return a value along with
        cutting short its hook chain, it will have to pass the return
        value via the short_circuit exception.

        The hooks.trigger() function will stop executing the hooks for
        key k when it sees a short_circuit exception.

        @note As mentioned earlier, although you can use any
        (reasonable) type for the hook map's keys, in Minx, we use
        strings as the keys. That is, pass a string as the first
        parameter k.

        """
        ret = []
        if k in self._hooks:
           logger.debug('triggering {} hooks'.format(k))
           try:
               for f in self._hooks[k]:
                   ret.append(f(*p))
           except short_circuit as e:
               ret.append(e.retval)
        return ret

    # Get all the currently defined keys
    def names(self):
        """Get names of currently defined hooks.

        @return List of strings containing names of currently defined hooks.

        This function returns the names of all the currently defined
        hooks. Callers should not rely on the returned names being in
        any particular order.

        @note Although Minx uses strings for the keys in its hook map,
        if end-users add hooks using keys of other types, the returned
        list will contain those types as well. That is, Minx makes no
        effort to enforce using strings as hook names. If you do, that's
        fine; however, those particular hooks will not be triggered (so
        don't waste your time and your computer's resources).

        """
        return self._hooks.keys()

    # What is the maximum priority for some key?
    def max_priority(self, k):
        """Priority value of highest-priority hook for some key.

        @param  k The name of the hook.
        @return Priority (integer) of highest-priority hook corresponding to k.

        This function is intended to allow end-users to determine the
        priority of the current highest-priority hook function
        corresponding to k so that they can insert higher priority
        functions. Here is a somewhat contrived snippet of code
        illustrating typical usage:

        @verbatim
            #!/usr/bin/env python

            import minx

            def my_manage_hook(w):
                prop = w.properties()
                if prop['class'].lower() == 'gkrellm':
                   return False
                return True

            # Create window manager
            wm = minx.core.wm()

            # Ensure my_manage_hook is the first to execute
            m = wm.hooks.max_priority('manage_hook')
            if m < 0: # no manage_hook installed
               m = wm.hooks.default_priority() + 1
            else: # some module installed a manage_hook
               m = m + 1
            wm.hooks.add('manage_hook', my_manage_hook, m)

            # Okay, let's run the window manager...
            wm.start()
        @endverbatim

        The above example is contrived because if that is all your Minx
        start-up file contained, there would be no manage_hook
        installed and, so, no need to check to ensure that
        my_manage_hook() would execute first. Furthermore, usually,
        only a single manage_hook would be needed; there's no point to
        having multiple manage hooks.

        Moreover, to add a hook at the highest priority, you can simply
        pass MAX_PRIORITY to the call to hooks.add() instead of going
        about it yourself. For example, to add the highest priority hook
        for some event 'foo', you could just call the hooks.add() method
        as shown below:

        @verbatim
            wm.hooks.add('foo', my_foo_hook, wm.hooks.MAX_PRIORITY)
        @endverbatim

        Nonetheless, the example serves to illustrate how and why you
        might want to use the hooks.max_priority() function.

        Note that if the hook map does not contain any hooks for the
        key k, this function will return a negative number.

        @note As mentioned earlier, although you can use any
        (reasonable) type for the hook map's keys, in Minx, we use
        strings as the keys. That is, pass a string for the parameter k.

        """
        if k in self._hooks:
           return self._hooks[k].max_priority()
        return -1

    # What is the minimum priority for some key?
    def min_priority(self, k):
        """Priority value of lowest-priority hook for some key.

        @param  k The name of the hook.
        @return Priority (integer) of lowest-priority hook corresponding to k.

        This function is intended to allow end-users to determine the
        priority of the current lowest-priority hook function
        corresponding to k so that they can insert lower priority
        functions.

        Here is a somewhat contrived snippet of code illustrating
        typical usage:

        @verbatim
            #!/usr/bin/env python

            import minx

            def my_manage_hook(w):
                prop = w.properties()
                if prop['class'].lower() == 'gkrellm':
                   return False
                return True

            # Create window manager
            wm = minx.core.wm()

            # Ensure my_manage_hook is the last to execute
            m = wm.hooks.min_priority('manage_hook')
            if m < 0: # no manage_hook installed
               m = wm.hooks.default_priority() - 1
            else: # some module installed a manage_hook
               m = m - 1
            wm.hooks.add('manage_hook', my_manage_hook, m)

            # Okay, let's run the window manager...
            wm.start()
        @endverbatim

        The above example is contrived because if that is all your Minx
        start-up file contained, there would be no manage_hook
        installed and, so, no need to check to ensure that
        my_manage_hook() would execute last. Furthermore, usually,
        only a single manage_hook would be needed; there's no point to
        having multiple manage hooks.

        Moreover, to add a hook at the lowest priority, you can simply
        pass MIN_PRIORITY to the call to hooks.add() instead of going
        about it yourself. For example, to add the lowest priority hook
        for some event 'foo', you could just call the hooks.add() method
        as shown below:

        @verbatim
            wm.hooks.add('foo', my_foo_hook, wm.hooks.MIN_PRIORITY)
        @endverbatim

        Nonetheless, the example serves to illustrate how and why you
        might want to use the hooks.min_priority() function.

        If the hook map does not contain any hooks for the key k, this
        function will return a negative number.

        @note Typically, you would want your hooks to execute before
        currently installed hooks. Thus, this function is much less
        useful than hooks.max_priority(), but is provided for the sake
        of completeness and just in case someone or some situation
        finds it necessary.

        """
        if k in self._hooks:
           return self._hooks[k].min_priority()
        return -1

    # Default hook priority
    def default_priority(self):
        """Default priority for hooks.

        @return Integer specifying default hook priority.

        To allow end-users greater control over the execution order of
        hook functions, the minx.core.hooks.hooks class arranges hook
        functions according to priorities, which must be integers in
        the range [1, 100]. Higher priority hooks are executed before
        lower priority ones.

        If end-users don't specify the priority for a hook, it will be
        assigned the default priority, which is the value returned by
        this function.

        @note Since hook priorities must lie in [1, 100], we use 50 as
        the default priority as this will allow end-users to add their
        hooks both above and below the default level.

        """
        return 50

#------------------------- CLASS DEFINITION ----------------------------

class short_circuit(Exception):
    """@ingroup grp_minx_core_hooks
    An exception for cutting short the execution of a chain of hooks.

    This class allows an end-user hook function to have Minx stop
    excecuting the remaining hooks in its chain of hooks.

    @note In addition to being a customization mechanism available to
    end-users, Minx also uses hooks internally for various purposes.
    All hooks, internal and external, are stored in a single hook map
    maintained by the @ref minx.core.wm.wm "main window manager object".
    This design allows for a very powerful way of customizing the
    window manager because it gives you access to even the low-level X
    event processing...

    @par
    However, with great power comes great responsibilty! In general, it
    would be unwise to short-circuit Minx's internal hooks. That is,
    <em>just because you can, doesn't mean you should</em>. As a rule
    of thumb, use short-circuting only when you're absolutely sure it
    won't have an adverse effect.

    @par
    For example, the <tt>manage_hook</tt> is expected to return True or
    False depending on whether it wants a particular window managed or
    not. While it would be unusual to have more than one
    <tt>manage_hook</tt> (because one hook can perform multiple checks
    on window properties for all window types), if you do have more than
    one <tt>manage_hook</tt>, the one that returns a False can
    short-circuit the rest because Minx will only manage a window if all
    the manage hooks return True. Thus, if even one returns False,
    there's no point executing the remaining hooks; that one can simply
    short-circuit the rest of the <tt>manage_hook</tt> chain.

    """
    def __init__(self, ret = None):
        """Create a short_circuit exception with the specified return value.

        @param ret The hook's return value (default = None).

        If a function raises an exception, it cannot also communicate a
        return value to its caller using the usual function return
        mechanism. Instead, we allow the short-circuiting hook to stuff
        its return value into the short_circuit exception. The
        hooks.trigger() function will extract the return value from its
        short_circuit exception handler and also stop executing the
        remaining hooks in the short-circuiting hook's chain.

        Here is an example of an end-user hook short-circuiting its
        chain of hooks and returning a value:

        @verbatim
            #!/usr/bin/env python

            import minx
            from minx.core.hooks import short_circuit

            def my_manage_hook(w):
                prop = w.properties()
                if prop['class'].lower() == 'gkrellm':
                   raise short_circuit(False)
                return True

            wm = minx.core.wm()
            wm.hooks.add('manage_hook', my_manage_hook)
            wm.start()
        @endverbatim

        @note The return value can be anything the hook function wants
        to return. The exception and hooks classes don't care about it;
        they simply pass it back to the Minx function that triggered the
        hooks.

        """
        self.retval = ret

#------------------------- CLASS DEFINITION ----------------------------

class priority_queue:
    """@ingroup grp_minx_core_hooks
    A helper class for Minx's hooks implementation.

    This class implements a priority queue that the hooks class can use
    to prioritize its hook function lists.

    @note This class is not a general-purpose priority queue
    implementation. It is specifically designed for use by the
    minx.core.hooks.hooks class. It is also not meant to be used by
    end-users, who should treat it as internal to Minx.

    """

    # Constructor
    def __init__(self):
        """Create an empty priority queue.

        """
        self._queue  = [] # the priority queue
        self._values = {} # all values stored in p.q. (to prevent duplication)
        self._count  = 0  # for ordering values of the same priority

    # Add element to priority queue
    # NOTE: We negate priority because the standard library's heapq
    # module defaults to a min heap while we want a max heap (so that
    # high-priority hooks are executed first).
    def add(self, v, p):
        """Add an element with specified priority.

        @param  v The value to be added to the priority queue.
        @param  p The priority of the value to be added.
        @return False if priority queue already contains v; True otherwise.

        This function adds v with priority p to the priority queue.
        This function does not perform any checks on the value of p,
        requiring its caller to implement appropriate policies
        regarding priorities.

        If the priority queue already contains v, it will not be added
        again. Thus, clients can make repeated calls to this function
        with the same value without having to worry about creating
        duplicate entries.

        """
        if v not in self._values:
           heappush(self._queue, (-p, self._count, v)) # NOTE: -p for max heap
           self._values[v] = True # to prevent duplicate entries
           self._count += 1       # for ordering values of same priority
           return True
        return False # priority queue already contains v

    # Priority of highest-priority item
    def max_priority(self):
        """Return priority of highest-priority item in priority queue.

        If the priority queue is empty, this function will return -1.

        """
        # Each item in the priority queue is a 3-tuple, the first element
        # of which is the negated priority (for making a max heap).
        if len(self._queue) <= 0:
           return -1
        return -self._queue[0][0]

    # Priority of lowest-priority item
    def min_priority(self):
        """Return priority of lowest-priority item in priority queue.

        If the priority queue is empty, this function will return -1.

        """
        # Each item in the priority queue is a 3-tuple, the first element
        # of which is the negated priority (for making a max heap).
        if len(self._queue) <= 0:
           return -1
        return -self._queue[-1][0]

    # Iterator interface
    def __iter__(self):
        """Iterator interface to priority queue.

        This function returns an iterator for accessing the priority
        queue's elements in order of descending priority.

        """
        # Helper class to implement priority queue iterator
        class _iterator_adaptor:
            def __init__(self, pq):
                self._iter = iter(pq)
            def next(self):
                p, c, v = self._iter.next()
                return v # queue stores priority and count; we only want value
        return _iterator_adaptor(self._queue)

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

##
# @file  layman.py
# @brief Class to manage layouts.
# @defgroup grp_minx_core_layman Layout Manager
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#-------------------------- MODULE DOC STRING ---------------------------

"""@ingroup grp_minx_core_layman
A helper for managing layouts.

This module defines helper classes for dealing with different layouts.
The layouts member of the @ref minx.core.wm.wm "main window manager object"
is an instance of the layout manager class. Both the main window manager
object as well as end-user code will use the layouts object to interface
with the different layout objects that Minx currently has.

"""

#------------------------------- IMPORTS --------------------------------

# Standard library
import logging

# Minx
from minx import layout

#---------------------------- MODULE LOGGER -----------------------------

logger = logging.getLogger(__name__)

#-------------------------------- CLASS ---------------------------------

class layman:
    """@ingroup grp_minx_core_layman
    Layout manager.

    This class keeps track of the different layout objects created by
    end-users and also provides a convenient API for dealing with these
    layouts.

    """

    # Constructor
    def __init__(self, wm):
        """Construct layout manager.

        @param wm The @ref minx.core.wm.wm "main window manager object".

        The layout manager is meant to be used by the
        @ref minx.core.wm.wm "main window manager object". When the
        layout manager is created, we squirrel away a reference to the
        main wm object so we can later get access to the "global"
        @ref minx.core.config.config "config" object and any other things
        we might need from the wm object.

        """
        self._wm = wm
        self._layouts = []

    # Add a layout object to internal list
    def add(self, layout):
        """Add given layout object to the layout manager.

        @param layout The layout object to be added.

        This method adds the specified layout object to the layout
        manager's internal list and performs other necessary bookkeeping.

        """
        self._layouts.append(layout)

    # Find layout corresponding to specified window or name
    def find(self, w):
        """Return layout object given either its X window or the window's name.

        @param  w A string or the @ref minxlib::window "minxlib.window" to find.
        @return Layout matching w.

        This method searches all the layouts currently being managed by
        the layout manager to see if any of them corresponds to the
        window w. If w is a string, then this method will look for a
        layout whose X window has the string w in its name.

        If there is no matching layout, this function will raise an
        unknown_layout exception.

        """
        if isinstance(w, str):
           logger.debug('looking for layout with "{}" in its name'.
                        format(w))
           for layout in self._layouts:
               name = layout.window.properties()['name']
               if w in name:
                  return layout
        else: # assume w refers to a minxlib.window
           logger.debug('looking for layout corresponding to window ID {}'.
                        format(w.id))
           for layout in self._layouts:
               if layout.window == w:
                  return layout
        raise unknown_layout(w)

    # Return layout with window that has the input focus
    def focused_layout(self):
        """Return current layout.

        This method returns the layout that has the top-level window that
        currently has the input focus. If no window has the input focus
        or if there is no layout corresponding to the focused window,
        this method will return None.

        """
        logger.debug('looking for focused layout')
        w = self._wm.display.get_focused_window()
        logger.debug('focused window = {}'.format(w.id))
        if w.id == 0:
           logger.debug('no window currently focused')
           return None

        try:
            p = w.parent()
            logger.debug('focused window = {}, its parent = {}'.
                         format(w.id, p.id))
            return self.find(p)
        except unknown_layout:
            logger.debug('no layout corresponding to focused window {}'.
                         format(w.id))
            return None

    # Find layout for new window
    def receptive_layout(self, w):
        """Find a layout to manage a new window.

        @param w The @ref minxlib::window "minxlib.window" to be managed.

        When a new window is created, Minx has to find a layout that will
        manage it. For lack of a better term, we refer to this layout as
        the receptive layout (because it will "receive" the new window).
        To find a layout willing and able to manage the new window, this
        function follows the procedure outlined below:

            @li Trigger the <tt>receptive_layout_hook</tt>.
            @li Failing that, check the focused layout.
            @li Failing that, search the remaining layouts.
            @li Failing that, create a new default layout.

        The <tt>receptive_layout_hook</tt> gives end-user code an
        opportunity to fine-tune the layout to be used for each window.
        If you have multiple functions for this hook, only the return
        value of the first one will be considered. That is, use only one
        hook for this; in fact, you shouldn't need an entire chain of
        hooks for the <tt>receptive_layout_hook</tt>.

        Minx will only accept the return value of the
        <tt>receptive_layout_hook</tt> if all of the following conditions
        are true:

            @li The return value is not None.
            @li It is an instance of the
                @ref minx.layout.base.base "minx.layout.base" class.
            @li The layout is on the same screen as w.
            @li The layout is willing to manage w.

        If the above-mentioned hook is not defined or if it returns
        something not fulfilling the above conditions, we check if the
        layout with the window that is currently focused is on the same
        screen as the new window and is willing to manage it. If so, this
        function will return the currently focused layout as the
        receptive layout, i.e., the layout that will manage the new
        window.

        If no window has the input focus, or if the focused layout is not
        on the same screen as the new window, or if it is unwilling to
        manage the new window, then we search the layout manager's
        remaining layouts for a layout that is on the same screen as the
        new window and is willing to manage it.

        If no such layout exists, Minx will fall back to creating a new
        layout object on the same screen as the new window and use that
        as the receptive layout. The layout class used for this fallback
        policy is referred to as the default layout. Currently, Minx uses
        the @ref minx.layout.full.full "full layout" as the default
        layout class.

        @note End-user code should not need to call this function.
        Specifically, don't call this function from your
        <tt>receptive_layout_hook</tt>.

        """
        s = w.screen()
        logger.debug('looking for receptive layout for window {} on screen {}'.
                     format(w.id, s))

        logger.debug('looking for receptive layout via user hook')
        U = self._wm.hooks.trigger('receptive_layout_hook', w)
        if len(U) > 0:
           logger.info('receptive_layout_hook returned {}'.format(U[0]))
           if (U[0] != None and isinstance(U[0], layout.base) and
               U[0].window.screen() == s and U[0].will_manage(w)):
               if not U[0] in self._layouts:
                  self.add(U[0])
               return U[0] # use first layout returned by hook
           else:
               logger.warning('bad layout ({}) '.format(U[0]) +
                              'returned by receptive_layout_hook')

        F = self.focused_layout()
        logger.debug('checking focused layout {} for receptivity'.format(F))
        if F != None and F.window.screen() == s and F.will_manage(w):
           logger.info('focused layout {} can and will manage window {}'.
                       format(F, w.id))
           return F

        logger.debug('checking remaining layouts for receptivity')
        for L in self._layouts:
            if L == F:
               continue
            if L.window.screen() == s and L.will_manage(w):
               logger.info('layout {} can and will manage window {}'.
                           format(L, w.id))
               return L

        logger.debug('no receptive layout found')
        D = layout.full(self._wm, self._wm.root_windows[s])
        self.add(D)
        logger.info('falling back to default layout {} for window {}'.
                    format(D, w.id))
        return D

#----------------------------- EXCEPTIONS -------------------------------

class unknown_layout(Exception):
    """@ingroup grp_minx_core_layman
    Unknown layout exception.

    The layout manager raises this exception when it fails to find a
    layout object corresponding to some window.

    """
    def __init__(self, w):
        """Construct an unknown_layout.

        @param w The @ref minxlib::window "minxlib.window" or window name
        for which there is no corresponding layout.

        The parameter w can be accessed as the exception's window member.

        """
        self.window = w

#------------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

##
# @file  window.py
# @brief Convenience functions for working with windows.
# @defgroup grp_minx_core_window Window Convenience API
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#-------------------------- MODULE DOC STRING ---------------------------

"""@ingroup grp_minx_core_window
Convenience functions for working with windows.

This module defines some convenience functions for dealing with
minxlib.window objects. Although you could simply call minxlib.window
functions directly, the functions defined in this module are more
convenient and also take into account things such as settings in
minx.core.config.

"""

#------------------------------- IMPORTS --------------------------------

# Standard library
import logging

# minx
import minxlib

#---------------------------- MODULE LOGGER -----------------------------

logger = logging.getLogger(__name__)

#------------------------ CONVENIENCE FUNCTIONS -------------------------

# Reset border color and size to match focused window and then focus
# the window.
def focus(w, c):
    """@ingroup grp_minx_core_window
    Focus the specified window.

    @param w The minxlib.window object to be focused.
    @param c The minx.core.config object containing Minx settings.

    This function sets the window's border attributes to those of the
    active window and then raises and focuses the window.

    """
    logger.info('setting window {} border attributes: 0x{:0<6X}, {}'.
                format(w.id, c.active_border_color, c.active_border_size))
    w.set_border_attr(c.active_border_color, c.active_border_size)

    logger.debug('focusing window {}'.format(w.id))
    w.focus()

# Reset border color and size to match unfocused windows
def unfocus(w, c):
    """@ingroup grp_minx_core_window
    Unfocus the specified window.

    @param w The minxlib.window object to be unfocused.
    @param c The minx.core.config object containing Minx settings.

    This function sets the window's border attributes to those of
    inactive windows.

    """
    logger.info('setting window {} border attributes: 0x{:0<6X}, {}'.
                format(w.id, c.inactive_border_color, c.inactive_border_size))
    w.set_border_attr(c.inactive_border_color, c.inactive_border_size)

#------------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# wm.py -- main object for interacting with the Minx window manager
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------ MODULE DOC STRING ----------------------------

"""@package minx.core.wm
Main interface object for Minx's end-users.

This file defines the minx.core.wm.wm class, which can be used simply as
minx.core.wm.

"""

#----------------------------- IMPORTS ---------------------------------

# Standard library
import shlex, subprocess
import re, logging, logging.config
import sys, traceback

# Minx core
import window
from   layman     import layman
from   xevents    import xevents
from   hooks      import hooks
from   config     import config
from   focus_list import focus_list
import minxlib

# Minx layouts
from minx import layout

#-------------------------- MODULE LOGGER ------------------------------

logger = logging.getLogger(__name__)

#------------------------- CLASS DEFINITION ----------------------------

class wm:
    """Main window manager object.

    This class encapsulates all the internal state required by the
    window manager. Typically, you will create an instance of this class
    in order to start the window manager. For example, the simplest Minx
    configuration would be a file with the following contents:

    @verbatim
        #!/usr/bin/env python
        import minx
        minx.core.wm().start()
    @endverbatim

    Of course, the above code requires the minx package to be in your
    Python path. But, assuming that is the case, it would start Minx
    with the default key bindings, hooks, and other settings.

    To make simple customizations, create an instance of the
    @ref minx.core.config.config "config" class and pass that to the wm
    constructor:

    @verbatim
        #!/usr/bin/env python

        import minx

        conf = minx.core.config()
        conf.active_border_color = 0x00FF00 # green

        minx.core.wm(conf).start()
    @endverbatim

    In addition to customizing window border attributes, the config
    class enables logging to be configured. Here is an example:

    @verbatim
        #!/usr/bin/env python

        import logging
        import minx

        conf = minx.core.config()
        conf.log_to_file('minx.log')
        conf.log_level(logging.DEBUG)

        minx.core.wm(conf).start()
    @endverbatim

    The <a href="../wiki/logging.wiki">Logging HOWTO</a> provides more
    details on logging configuration.

    Apart from the simple attribute customizations shown above, if you
    would also like to change the way Minx responds to various events,
    you will have to define hook functions and pass those to Minx. Here
    is a simple example:

    @verbatim
        #!/usr/bin/env python

        import minx

        def my_manage_hook(w):
            prop = w.properties()
            if prop['class'].lower() == 'gkrellm':
               return False
            return True

        wm = minx.core.wm()
        wm.hooks.add('manage_hook', my_manage_hook)
        wm.start()
    @endverbatim

    The above configuration will setup a manage hook that instructs Minx
    to ignore the GKrellM window. Have a look at the
    <a href="../wiki/hooks-howto.wiki">Hooks HOWTO</a> for lots more
    info about configuring Minx using hooks. Additionally, the
    <a href="../wiki/hooks-list.wiki">Hooks List</a> documents all the
    hooks that Minx currently supports.

    One important use of hooks is for defining custom key bindings. The
    <a href="../wiki/key-bindings.wiki">Key Bindings HOWTO</a> has the
    details.

    To customize how Minx arranges windows, you can:

        @li Specify the layouts you would like to use
        @li Specify the layout for particular windows
        @li Implement your own layouts

    Here is an example that illustrates the first two of the above
    possibilities:

    @verbatim
        #!/usr/bin/env python

        import minx

        def my_init_hook(m):
            scr = m.root_windows
            m.layouts.add(minx.layout.tall(m, scr[0]))
            m.layouts.add(minx.layout.rows(m, scr[1]))

        def my_receptive_layout_hook(w):
            prop = w.properties()
            if 'gimp' in prop['class'].lower():
                global wm
                try:
                    L = wm.layouts.find('gimp')
                    return L
                except minx.core.layman.unknown_layout:
                   parent = wm.root_windows[w.screen()]
                   return minx.layout.gimp(wm, parent)
            return None

        wm = minx.core.wm()
        wm.hooks.add('init_hook', my_init_hook)
        wm.hooks.add('receptive_layout_hook', my_receptive_layout_hook)
        wm.start()
    @endverbatim

    The <a href="../wiki/hooks-list.wiki#init_hook">init hook</a> allows
    you to setup the layouts you want to use. If you don't supply an init
    hook, Minx will use a default layout for each screen. At this time,
    the default layout is the @ref minx.layout.full.full "full" layout,
    which shows one window at a time by resizing windows to occupy the
    entire screen. In the above example, we use the tall layout for the
    first screen and the rows layout for the second screen. Of course,
    this would only work if you actually have two screens. Please also
    note that the tall and rows layout classes have not yet been
    implemented; we use these nonexistent layouts just to illustrate the
    intended spirit of layouts specification.

    The <a href="../wiki/hooks-list.wiki#receptive_layout_hook">receptive
    layout hook</a> allows you to either create or find a layout for each
    new window that Minx manages. In the above example, we created an
    instance of the gimp layout when Gimp starts up and use that for
    subsequent windows. For all other window types, we fall back to
    either the tall or rows layouts setup in the init hook. If, for some
    reason, the tall and rows layouts refuse to manage the new window,
    Minx will fall back its default, viz., the full layout. Again, like
    tall and rows, the gimp layout does not exist yet; it was used merely
    to illustrate how the receptive layout hook is intended to work.

    Documentation for implementing layouts will come later.

    @note Although this class is defined in the minx.core.wm "package"
    and, technically, must be accessed as minx.core.wm.wm, it can, in
    fact (and as illustrated in the code snippets above), be referred to
    simply as minx.core.wm.

    """
    # Constructor
    def __init__(self, conf = None):
        """Create the main window manager object.

        @param conf Config object containing simple customizations.

        The wm class implements the main interface to the Minx window
        manager. You will have to first create an instance of this class
        and then call its start() method to run the window manager. This
        constructor simply sets up some internal attributes, the most
        important of which are:

            @li config
            @li hooks
            @li layouts

        The @ref minx.core.config.config "config" object specifies
        various settings such as the border colors, sizes, etc. To
        customize these settings, you will (typically) create a config
        object, change its various attributes, and pass that object into
        this constructor. (Alternatively, you could first create a wm
        object and then access its config attribute.) If you don't supply
        a config object, the window manager will use default settings.

        The wm object's @ref minx.core.hooks.hooks "hooks" attribute
        maps names of hook functions (i.e., strings) to prioritized
        lists of callables. Minx will trigger these hooks at appropriate
        points in its event processing workflow. Minx uses hooks both
        internally (to handle various events) and "externally" (to allow
        end-users to customize its behaviour).

        To supply your own hooks, after creating a wm instance, use its
        hooks attribute to add hook functions for various events. Take a
        look at the <a href="../wiki/hooks-howto.wiki">Hooks HOWTO</a>
        for more on customizing Minx with hook functions. The
        <a href="../wiki/hooks-list.wiki">Hooks List</a> documents all
        the hooks currently supported by Minx.

        As mentioned earlier, Minx leverages its hooks mechanism to
        allow end-users to define custom key bindings. The
        <a href="../wiki/key-bindings.wiki">Key Bindings HOWTO</a>
        explains this feature.

        One thing to keep in mind about hooks is that, since Minx uses
        them internally, it is easy to override its internal hooks and
        even disable them. Usually, this will cause Bad Things (TM) to
        happen. Thus, you should exercise care when dealing with
        "dangerous" hooks. As long as you stick to "external" hooks used
        by Minx specifically to effect customization, you should be
        okay.

        Finally, the @ref minx.core.layman.layman "layouts" object
        provides an interface for dealing with window layouts. By
        default, Minx uses the @ref minx.layout.full.full "full" layout,
        which shows one window at a time, resizing windows so that they
        occupy the entire screen. You can use the
        <a href="../wiki/hooks-list.wiki#init_hook">init hook</a> to add
        your preferred layouts to the layout manager.

        Another way to customize layout selection is to use the
        <a href="../wiki/hooks-list.wiki#receptive_layout_hook">receptive
        layout hook</a>, which provides a mechanism for deciding a layout
        for each new window.

        """
        if conf == None: # create a default config object
           conf =  config()
        self.config = conf

        # Configure Minx's root logger
        logging.config.dictConfig(conf.logger)
        logger.info('starting Minx')

        # Other initialization
        logger.debug('creating focus list')
        self._focus_list = focus_list()

        logger.debug('creating layout manager')
        self.layouts = layman(self)

        logger.info('setting up X event handlers and default keybindings')
        self.hooks = hooks()
        self._xevents = xevents(self)
        self._init_keybindings()

        self._quit = False

    # Default keybindings
    def _init_keybindings(self):
        self.hooks.add(  'A-Tab', self.focus_next)
        self.hooks.add('S-A-Tab', self.focus_prev)
        self.hooks.add(   'A-F4', self.kill)
        self.hooks.add(   'C-F4', self.nuke)
        self.hooks.add(  'C-A-T', lambda: self.spawn(self.config.terminal))
        self.hooks.add(  'C-A-X', self.quit)

    # Start the window manager
    def start(self):
        """Start the window manager.

        Call this method after creating a wm instance to get Minx up and
        running. Here is an example showing how to start Minx with its
        default settings, key bindings, etc.:

        @verbatim
            #!/usr/bin/env python
            import minx
            minx.core.wm().start()
        @endverbatim

        If you would like to customize Minx by specifying your own hooks
        to be able to deal with various events, the initialization and
        start-up sequence will be a three step procedure as shown below:

        @verbatim
            #!/usr/bin/env python

            import minx

            # Define your hook functions
            def my_manage_hook(w):
                return True # actually, you would do something more useful

            # Step one: create window manager object
            wm = minx.core.wm()

            # Step two: customize using hooks
            wm.hooks.add('manage_hook', my_manage_hook)
            wm.hooks.add(  'F1', wm.focus_next) # custom key binding
            wm.hooks.add('S-F1', wm.focus_prev) # custom key binding

            # Step three: start the window manager
            wm.start()
        @endverbatim

        """
        self.connect_x()
        self.configure_x()
        self.hooks.trigger('init_hook', self)
        self.manage_existing()
        self.event_loop()

    # Connect to the X server
    def connect_x(self):
        """Connect to the X server.

        This method connects to the X server. If we are unable to do so,
        it will raise a minxlib.connection_error.

        @note This method is mostly an internal one meant to be used by
        Minx itself. In fact, it is called by wm.start(). You should not
        really need to call it yourself. However, we provide this as a
        public method to allow customization in case you want to do
        something after connecting to X but before the other steps in
        Minx's usual start-up sequence.

        @par
        If you decide not to use wm.start(), look at the Minx code to
        see how and what you will need to do to effectively use this
        function.

        """
        try:
            conf = self.config
            logger.info('connecting to X server (synchronous = {})'.
                        format(conf.synchronize_xlib))
            self.display = minxlib.display(sync = conf.synchronize_xlib)
        except minxlib.connection_error as e:
            logger.critical(e)
            raise

    # Configure X to send us events we need to manage windows
    def configure_x(self):
        """Configure X server to send Minx events it needs to manage windows.

        This method sets up the event mask for all the root windows so
        that Minx gets the notifications it needs to be able to manage
        windows. It also sets up passive keyboard grabs to make the
        keybindings mechanism work.

        @note This method is mostly an internal one meant to be used by
        Minx itself. In fact, it is called by wm.start(). You should not
        really need to call it yourself. However, we provide this as a
        public method to allow customization in case you want to do
        something after connecting to and setting up X but before the
        remaining steps in Minx's usual start-up sequence.

        @par
        If you decide not to use wm.start(), look at the Minx code to
        see how and what you will need to do to effectively use this
        function.

        """
        # Find hooks that correspond to key bindings
        logger.info('finding key binding hooks')
        km = '|'.join(self.display.get_keyboard_mapping())
        kb = re.compile('^(([CAS]|M[1-5]?)-)*(' + km + ')$')
        key_bindings = [n for n in self.hooks.names() if kb.search(n)]
        #logger.debug('km = {}'.format(km))
        logger.debug('key bindings hooks = {}'.format(' '.join(key_bindings)))

        # Setup event masks and passive grabs for all screens
        self.root_windows = self.display.get_root_windows()
        for w in self.root_windows:
            logger.info('configuring root window {}'.format(w.id))
            w.select_events(minxlib.substructure_redirect_mask |
                            minxlib.substructure_notify_mask   |
                            minxlib.key_press_mask)
            for k in key_bindings:
                w.grab_key(k)

    # Manage extant top-level windows (we won't get create notifications
    # for these).
    def manage_existing(self):
        """Manage existing top-level windows.

        Minx uses this function to get the list of existing top-level
        windows and add them to its internal data structures so it can
        manage them. This is necessary, for example, when an end-user's
        ~/.xinitrc starts X programs before starting the window manager.
        It is also required when the window manager is restarted or when
        a user switches from another running window manager to Minx.

        @note This method is mostly an internal one meant to be used by
        Minx itself. In fact, it is called by wm.start(). You should not
        really need to call it yourself. However, we provide this as a
        public method to allow customization in case you want to do
        something after connecting to X, setting it up, and managing the
        existing top-level windows but before entering the event loop.

        @par
        If you decide not to use wm.start(), look at the Minx code to
        see how and what you will need to do to effectively use this
        function.

        """
        logger.info('managing existing top-level windows')
        for w in self.display.get_top_level_windows():
            prop = w.properties()
            logger.debug('window {} class = {}, name = {}'.
                         format(w.id, prop['class'], prop['name']))
            if prop['class'] != 'minx.layout' and self.manage(w):
               self.layouts.receptive_layout(w).add(w)

    # Event loop
    def event_loop(self):
        """Retrieve and process X events.

        This method implements Minx's event loop. Once we enter this
        function, Minx will initiate an infinite loop, wherein it
        blocks, waiting for the X server to send it events. When it
        receives an event notification, it will trigger its internal
        event processing hooks to respond appropriately.

        @note This method is mostly an internal one meant to be used by
        Minx itself. In fact, it is called by wm.start(). You should not
        really need to call it yourself. However, we provide this as a
        public method to allow customization in case you want to do
        something after connecting to X, setting it up, and managing the
        existing top-level windows but right before entering the event
        loop.

        @par
        If you decide not to use wm.start(), look at the Minx code to
        see how and what you will need to do to effectively use this
        function.

        """
        logger.info('entering event loop')
        while not self._quit:
            try:
                logger.debug('waiting for event')
                e = self.display.get_event()
                logger.debug('got event {}'.format(e))
                self.hooks.trigger(str(e), e)

            # Tried to query the window hierarchy of a non-existent
            # window. This happens when a window is destroyed and we
            # receive various other notifications before the destroy
            # notification comes in. Well, there's not much to be done in
            # this situation; so, just log the error and keep going.
            except minxlib.query_tree_error as e:
                logger.warning(e)

            # Tried to focus a non-existent window (happens sometimes
            # upon window destruction, causing the resulting unmap and
            # focus notification handlers to go out-of-sync with the X
            # server's internal state). We can use the protocol error
            # that ensues as an opportunity to sync the internal states
            # of the window manager and X server.
            except minxlib.set_focus_error as e:
                logger.warning(e)
                self._focus_list.remove(e.resource_id)

            # Tried to change attributes of a non-existent window. This
            # used to happen when a window was destroyed and the
            # resulting focus_out event handler's attempt to set its
            # border color to the inactive window border color causes
            # unnecessary pain...
            #
            # However, now that we no longer rely on X's focus change
            # events to perform the window border update, this exception
            # should not be generated and its handler no longer
            # required. Nonetheless, it is in place for now; we can
            # remove it later on during development when the design has
            # stabilized enough for us to be absolutely sure this bit of
            # code is no longer required.
            except minxlib.change_window_attributes as e:
                logger.warning(e)
                if e.error_code == minxlib.bad_window:
                   pass # ignore protocol error (should be okay)

            # Generic protocol error
            except minxlib.protocol_error as e:
                logger.warning(e)

            # Some other exception: log it and keep going
            except:
                logger.warning('received {} exception'.
                               format(sys.exc_info()[0]))
                logger.debug(traceback.format_exc())

        logger.info('exiting event loop')


    # API to focus next window
    def focus_next(self):
        """Focus next window.

        This function passes input focus to the next window in the
        window manager's list of top-level windows that can accept input
        focus. It is meant to be invoked via a key binding's hook. Here
        is an example of intended usage:

        @verbatim
            #!/usr/bin/env python

            import minx

            wm = minx.core.wm()
            wm.hooks.add(  'F1', wm.focus_next)
            wm.hooks.add('S-F1', wm.focus_prev)
            wm.start()
        @endverbatim

        With that in your Minx start-up script, you will be able to
        cycle input focus with F1 and SHIFT + F1 (in addition to the
        default key bindings for focus cycling, viz., ALT + Tab and
        ALT + SHIFT + Tab).

        """
        L = self._focus_list
        old_head = L.head()
        L.forward()
        new_head = L.head()
        if new_head != old_head:
           logger.info('switching focus from {} to {}'.
                       format(old_head.id, new_head.id))
           window.unfocus(old_head, self.config)
           window.  focus(new_head, self.config)
        #else: new_head == old_head ==> focus list empty or only one window

    # API to focus previous window
    def focus_prev(self):
        """Focus previous window.

        This function passes input focus to the previous window in the
        window manager's list of top-level windows that can accept input
        focus. It is meant to be invoked via a key binding's hook. Here
        is an example of intended usage:

        @verbatim
            #!/usr/bin/env python

            import minx

            wm = minx.core.wm()
            wm.hooks.add(  'F1', wm.focus_next)
            wm.hooks.add('S-F1', wm.focus_prev)
            wm.start()
        @endverbatim

        With that in your Minx start-up script, you will be able to
        cycle input focus with F1 and SHIFT + F1 (in addition to the
        default key bindings for focus cycling, viz., ALT + Tab and
        ALT + SHIFT + Tab).

        """
        L = self._focus_list
        old_head = L.head()
        L.backward()
        new_head = L.head()
        if new_head != old_head:
           logger.info('switching focus from {} to {}'.
                       format(old_head.id, new_head.id))
           window.unfocus(old_head, self.config)
           window.  focus(new_head, self.config)
        #else: new_head == old_head ==> focus list empty or only one window

    # Kill a window
    def kill(self, w = None):
        """Kill window.

        @param w The @ref minxlib::window "minxlib.window" to be killed.

        This function kills the X client application that created the
        window w and all of its other windows and X resources. If w is
        not supplied by the caller, this function will kill the
        currently focused window.

        """
        if w == None: # kill the currently focused window
           w = self._focus_list.head()
        if w != None: # there is a focused window to kill
           w.kill()

    # Kill a window using brute force
    def nuke(self, w = None):
        """Kill window using brute force.

        @param w The @ref minxlib::window "minxlib.window" to be nuked.

        This function kills the X client application that created the
        window w and all of its other windows and X resources. If w is
        not supplied by the caller, this function will kill the
        currently focused window.

        @note Whereas the kill() function attempts a graceful shutdown,
        this function resorts to brute force. It is meant to be used on
        windows that advertise support for the WM_DELETE_WINDOW protocol
        but don't implement it properly, thus, requiring a brute force
        kill (i.e., a nuking).

        """
        if w == None: # kill the currently focused window
           w = self._focus_list.head()
        if w != None: # there is a focused window to kill
           w.nuke()

    # Start an application
    def spawn(self, cmd):
        """Run specified command.

        @param cmd A string containing the command and command-line arguments.

        This function can be used to run arbitrary commands. Minx does
        not wait for the command to complete or communicate with it any
        further after starting it. The intent of this function is to
        facilitate launching GUI applications via window manager key
        bindings.

        If the command fails, Minx will write details to its log (if
        logging has been enabled).

        """
        logger.info('running command: {}'.format(cmd))
        try:
            subprocess.Popen(shlex.split(cmd))
        except:
            logger.warning('{} exception on command: {}'.
                           format(sys.exc_info()[0], cmd))
            logger.debug(traceback.format_exc())

    # Add newly created top-level window to focus list
    def add_to_focus_list(self, w):
        """Add a newly created top-level window to the focus list.

        @param w The @ref minxlib::window "minxlib.window" to be added.

        This function is meant to be used internally by Minx.
        Specifically, the wm constructor calls it to take over
        management of any top-level windows that might have been created
        before Minx was started. Also, the <tt>MapNotify</tt> handler in
        the xevents class uses it to add a newly mapped top-level window
        to the focus list and to focus it.

        End-users should not use this function.

        """
        L = self._focus_list
        f = L.head()
        if f != None:
           logger.debug('unfocusing {}'.format(f.id))
           window.unfocus(f, self.config)
        logger.debug('adding {} to focus list and focusing'.format(w.id))
        L.add(w)
        window.focus(w, self.config)

    # Whether or not manage the given window
    def manage(self, w):
        """Check if given window should be managed or not.

        @param  w The @ref minxlib::window "minxlib.window" to be checked.
        @return True if Minx should manage w, false if it should ignore w.

        This function triggers the manage hooks setup by end-users and
        checks all their return values. If all the manage hooks return
        True, then this function will return True. If any of the manage
        hooks returns False, this function will return False. Thus,
        Minx will only manage a top-level window if all the manage
        hooks return True.

        @note This function is meant to be used internally by Minx.
        End-user code should refrain from calling it.

        """
        # hooks.trigger() returns a list of return values of each hook
        # it calls.  The manage_hook expects a Boolean return value:
        # True to indicate that the window w should be managed, False
        # to make Minx ignore w. Thus, to determine whether w should be
        # managed, we have to examine the each of these return values
        # and confirm that they're all True.
        for r in self.hooks.trigger('manage_hook', w):
            if r == False:  # some manage hook returned False
               return False # therefore, ignore w

        # If we get here, all manage hooks passed w ==> we should
        # manage it...
        return True

    # Quit window manager
    def quit(self):
        """Quit the window manager.

        This function sets a flag that will eventually result in Minx
        exiting its event loop. It is meant to be invoked via a key
        binding or other similar action.

        """
        self._quit = True

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# xevents.py -- X event handlers
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------ MODULE DOC STRING ----------------------------

"""@package minx.core.xevents
Helper class for handling various X events.

"""

#----------------------------- IMPORTS ---------------------------------

# Standard library
import logging

# Minx
import layman
import window
import minxlib

#-------------------------- MODULE LOGGER ------------------------------

logger = logging.getLogger(__name__)

#------------------------- CLASS DEFINITION ----------------------------

class xevents:
    """Helper class for handling various X events.

    This class encapsulates the X event handlers so that the
    @ref minx.core.wm.wm "main window manager object" can delegate this
    low-level functionality. This class is not really meant to be used
    by end-users; it should be considered internal to Minx.

    """

    # Constructor
    def __init__(self, wm):
        """Initialize X event handlers.

        @param wm The @ref minx.core.wm.wm "main window manager object".

        This class is meant to be used by @ref minx.core.wm.wm "minx.core.wm"
        so the main window manager object can delegate all the low-level
        X event handling. Consequently, the xevents object needs a
        reference to the main window manager object so it can access and
        manipulate the window manager's internal state in response to
        various X events.

        """
        self._wm = wm
        self._init_hooks()

    # Helper function to initialize the mapping between X events and
    # their corresponding handler functions.
    #
    # NOTE: This relies on the string forms of all minxlib::event
    # subclasses being "x_something". Thus, the mapping between event
    # types and handlers uses strings as keys and functions as the
    # corresponding values.
    def _init_hooks(self):
        logger.debug('setting up X event handlers')
        h = self._wm.hooks
        h.add('x_create_notify',     self._on_create)
        h.add('x_configure_request', self._on_configure_request)
        h.add('x_map_request',       self._on_map_request)
        h.add('x_map_notify',        self._on_map)
        h.add('x_unmap_notify',      self._on_unmap)
        h.add('x_key_press',         self._on_key_press)

    # Whether or not window specified by x_create_notify event should
    # be managed by Minx or ignored.
    def _manage(self, e):
        prop = e.target.properties()
        logger.debug('window {} class = {}, name = {}'.
                     format(e.target.id, prop['class'], prop['name']))
        return (not e.override_redirect and
                prop['class'] != 'minx.layout' and
                e.parent in self._wm.root_windows and
                self._wm.manage(e.target))

    # When a new top-level window is created, the window manager has to
    # update its internal state to include this new window in its list
    # of top-level windows it has to manage.
    #
    # NOTE: We do not add new top-level windows to the focus list right
    # away. Instead, we wait for them to be mapped first before putting
    # them on the focus list. This is because some applications (e.g.,
    # GNOME and XFCE terminal) create hidden top-level windows that
    # should never receive input focus.
    def _on_create(self, e):
        if self._manage (e):
           self._wm.layouts.receptive_layout(e.target).add(e.target)

    # What to do when a window wants to be configured: pass configure
    # request through as-is except for top-level windows, which have to
    # be resized according to their managing layout's policy.
    def _on_configure_request(self, e):
        logger.info ('configure request for window {}'.format(e.target.id))
        logger.debug('configure request details: ' +
                     'geom = {}x{}+{}+{}, bw = {}, mask = {:#010b}'.
                     format(e.width, e.height, e.x, e.y,
                            e.border_width, e.value_mask))
        try:
            layout = self._wm.layouts.find(e.parent)
            x, y, w, h = layout.configure_request(e.target, e.x, e.y,
                                                  e.width, e.height)

        except layman.unknown_layout: # pass configure request through as-is
            logger.debug('window {} not a top-level window'.
                         format(e.target.id))
            x, y, w, h = (e.x, e.y, e.width, e.height)

        logger.debug('setting window {} geometry to {}x{}+{}+{}'.
                     format(e.target.id, w, h, x, y))
        e.target.configure(x, y, w, h, e.border_width,
                           e.above, e.stack_mode, e.value_mask)

    # What to do when a window wants to be shown on-screen: top-level
    # windows will be passed to their managing layout for possible
    # reconfiguration before being mapped; all other windows are mapped
    # as-is.
    def _on_map_request(self, e):
        logger.info('map request for window {}'.format(e.target.id))
        try:
            layout = self._wm.layouts.find(e.parent)
            layout.map_request(e.target)
        except layman.unknown_layout:
            pass
        e.target.show()

    # What to do when a top-level window is successfully shown
    # on-screen: we should add it to the window manager's focus list and
    # focus it.
    def _on_map(self, e):
        try:
            self._wm.layouts.find(e.parent)
            logger.debug('adding top-level window {} to focus list'.
                         format(e.target.id))
            self._wm.add_to_focus_list(e.target)
        except layman.unknown_layout: # not a top-level window
            pass

    # What to do when a top-level window is taken off-screen: remove it
    # from the window manager's focus list and focus the next window on
    # the focus list.
    def _on_unmap(self, e):
        try:
            self._wm.layouts.find(e.parent)
            L = self._wm._focus_list
            logger.info('removing {} from focus list'.format(e.target.id))
            L.remove(e.target)
            f = L.head()
            if f != None:
               logger.info('focusing {}'.format(f.id))
               window.focus(f, self._wm.config)
        except layman.unknown_layout: # not a top-level window
            pass

    # What to do when a key is pressed.
    def _on_key_press(self, e):
        logger.info('keypress: {}, keycode: {}, mask: {:#06x}'.
                    format(e.key, e.keycode, e.mask))
        self._wm.hooks.trigger(e.key)

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# Build spec for Minx's API docs
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki for the full list of authors who have
# contributed to this project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

# Min cmake version
cmake_minimum_required(VERSION 2.8)

# Project name
project(minxdoc)

# Check if we have Xinerama and, if so, set a CMake variable that will
# tell Doxygen so that it generates the documentation for the optional
# Xinerama-dependent parts of Minx.
find_package(X11)
if(X11_Xinerama_FOUND)
    set(minxdoc_PREDEFINED MINXLIB_HAS_XINERAMA)
endif()

# Custom target for API documentation
find_package(Doxygen)
if(DOXYGEN_FOUND)
    configure_file("${CMAKE_CURRENT_SOURCE_DIR}/doxyfile.in"
                   "${CMAKE_CURRENT_BINARY_DIR}/doxyfile" @ONLY)
    add_custom_target(doc
                      ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxyfile
                      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                      COMMENT "Generating documentation")
endif(DOXYGEN_FOUND)

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# sh-basic-offset: 4                         #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

/* The standard CSS for doxygen */

body, table, div, p, dl {
	font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif;
	font-size: 13px;
	line-height: 1.3;
}

/* @group Heading Levels */

h1 {
	font-size: 150%;
}

.title {
	font-size: 150%;
	font-weight: bold;
	margin: 10px 2px;
}

h2 {
	font-size: 120%;
}

h3 {
	font-size: 100%;
}

dt {
	font-weight: bold;
}

div.multicol {
	-moz-column-gap: 1em;
	-webkit-column-gap: 1em;
	-moz-column-count: 3;
	-webkit-column-count: 3;
}

p.startli, p.startdd, p.starttd {
	margin-top: 2px;
}

p.endli {
	margin-bottom: 0px;
}

p.enddd {
	margin-bottom: 4px;
}

p.endtd {
	margin-bottom: 2px;
}

/* @end */

caption {
	font-weight: bold;
}

span.legend {
        font-size: 70%;
        text-align: center;
}

h3.version {
        font-size: 90%;
        text-align: center;
}

div.qindex, div.navtab{
	background-color: #EBEFF6;
	border: 1px solid #A3B4D7;
	text-align: center;
}

div.qindex, div.navpath {
	width: 100%;
	line-height: 140%;
}

div.navtab {
	margin-right: 15px;
}

/* @group Link Styling */

a {
	color: #3D578C;
	font-weight: normal;
	text-decoration: none;
}

.contents a:visited {
	color: #4665A2;
}

a:hover {
	text-decoration: underline;
}

a.qindex {
	font-weight: bold;
}

a.qindexHL {
	font-weight: bold;
	background-color: #9CAFD4;
	color: #ffffff;
	border: 1px double #869DCA;
}

.contents a.qindexHL:visited {
        color: #ffffff;
}

a.el {
	font-weight: bold;
}

a.elRef {
}

a.code, a.code:visited {
	color: #4665A2; 
}

a.codeRef, a.codeRef:visited {
	color: #4665A2; 
}

/* @end */

dl.el {
	margin-left: -1cm;
}

.fragment {
	font-family: monospace, fixed;
	font-size: 105%;
}

pre.fragment {
	border: 1px solid #C4CFE5;
	background-color: #FBFCFD;
	padding: 4px 6px;
	margin: 4px 8px 4px 2px;
	overflow: auto;
	word-wrap: break-word;
	font-size:  9pt;
	line-height: 125%;
}

div.ah {
	background-color: black;
	font-weight: bold;
	color: #ffffff;
	margin-bottom: 3px;
	margin-top: 3px;
	padding: 0.2em;
	border: solid thin #333;
	border-radius: 0.5em;
	-webkit-border-radius: .5em;
	-moz-border-radius: .5em;
	box-shadow: 2px 2px 3px #999;
	-webkit-box-shadow: 2px 2px 3px #999;
	-moz-box-shadow: rgba(0, 0, 0, 0.15) 2px 2px 2px;
	background-image: -webkit-gradient(linear, left top, left bottom, from(#eee), to(#000),color-stop(0.3, #444));
	background-image: -moz-linear-gradient(center top, #eee 0%, #444 40%, #000);
}

div.groupHeader {
	margin-left: 16px;
	margin-top: 12px;
	font-weight: bold;
}

div.groupText {
	margin-left: 16px;
	font-style: italic;
}

body {
	background-color: white;
	color: black;
        margin: 0;
}

div.contents {
	margin-top: 10px;
	margin-left: 8px;
	margin-right: 8px;
}

td.indexkey {
	background-color: #EBEFF6;
	font-weight: bold;
	border: 1px solid #C4CFE5;
	margin: 2px 0px 2px 0;
	padding: 2px 10px;
        white-space: nowrap;
        vertical-align: top;
}

td.indexvalue {
	background-color: #EBEFF6;
	border: 1px solid #C4CFE5;
	padding: 2px 10px;
	margin: 2px 0px;
}

tr.memlist {
	background-color: #EEF1F7;
}

p.formulaDsp {
	text-align: center;
}

img.formulaDsp {
	
}

img.formulaInl {
	vertical-align: middle;
}

div.center {
	text-align: center;
        margin-top: 0px;
        margin-bottom: 0px;
        padding: 0px;
}

div.center img {
	border: 0px;
}

address.footer {
	text-align: right;
	padding-right: 12px;
}

img.footer {
	border: 0px;
	vertical-align: middle;
}

/* @group Code Colorization */

span.keyword {
	color: #008000
}

span.keywordtype {
	color: #604020
}

span.keywordflow {
	color: #e08000
}

span.comment {
	color: #800000
}

span.preprocessor {
	color: #806020
}

span.stringliteral {
	color: #002080
}

span.charliteral {
	color: #008080
}

span.vhdldigit { 
	color: #ff00ff 
}

span.vhdlchar { 
	color: #000000 
}

span.vhdlkeyword { 
	color: #700070 
}

span.vhdllogic { 
	color: #ff0000 
}

/* @end */

/*
.search {
	color: #003399;
	font-weight: bold;
}

form.search {
	margin-bottom: 0px;
	margin-top: 0px;
}

input.search {
	font-size: 75%;
	color: #000080;
	font-weight: normal;
	background-color: #e8eef2;
}
*/

td.tiny {
	font-size: 75%;
}

.dirtab {
	padding: 4px;
	border-collapse: collapse;
	border: 1px solid #A3B4D7;
}

th.dirtab {
	background: #EBEFF6;
	font-weight: bold;
}

hr {
	height: 0px;
	border: none;
	border-top: 1px solid #4A6AAA;
}

hr.footer {
	height: 1px;
}

/* @group Member Descriptions */

table.memberdecls {
	border-spacing: 0px;
	padding: 0px;
}

.mdescLeft, .mdescRight,
.memItemLeft, .memItemRight,
.memTemplItemLeft, .memTemplItemRight, .memTemplParams {
	background-color: #F9FAFC;
	border: none;
	margin: 4px;
	padding: 1px 0 0 8px;
}

.mdescLeft, .mdescRight {
	padding: 0px 8px 4px 8px;
	color: #555;
}

.memItemLeft, .memItemRight, .memTemplParams {
	border-top: 1px solid #C4CFE5;
}

.memItemLeft, .memTemplItemLeft {
        white-space: nowrap;
}

.memItemRight {
	width: 100%;
}

.memTemplParams {
	color: #4665A2;
        white-space: nowrap;
}

/* @end */

/* @group Member Details */

/* Styles for detailed member documentation */

.memtemplate {
	font-size: 80%;
	color: #4665A2;
	font-weight: normal;
	margin-left: 9px;
}

.memnav {
	background-color: #EBEFF6;
	border: 1px solid #A3B4D7;
	text-align: center;
	margin: 2px;
	margin-right: 15px;
	padding: 2px;
}

.mempage {
	width: 100%;
}

.memitem {
	padding: 0;
	margin-bottom: 10px;
	margin-right: 5px;
}

.memname {
        white-space: nowrap;
        font-weight: bold;
        margin-left: 6px;
}

.memproto, dl.reflist dt {
        border-top: 1px solid #A8B8D9;
        border-left: 1px solid #A8B8D9;
        border-right: 1px solid #A8B8D9;
        padding: 6px 0px 6px 0px;
        color: #253555;
        font-weight: bold;
        text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9);
        /* opera specific markup */
        box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
        border-top-right-radius: 8px;
        border-top-left-radius: 8px;
        /* firefox specific markup */
        -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px;
        -moz-border-radius-topright: 8px;
        -moz-border-radius-topleft: 8px;
        /* webkit specific markup */
        -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
        -webkit-border-top-right-radius: 8px;
        -webkit-border-top-left-radius: 8px;
        background-image:url('nav_f.png');
        background-repeat:repeat-x;
        background-color: #E2E8F2;

}

.memdoc, dl.reflist dd {
        border-bottom: 1px solid #A8B8D9;      
        border-left: 1px solid #A8B8D9;      
        border-right: 1px solid #A8B8D9; 
        padding: 2px 5px;
        background-color: #FBFCFD;
        border-top-width: 0;
        /* opera specific markup */
        border-bottom-left-radius: 8px;
        border-bottom-right-radius: 8px;
        box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
        /* firefox specific markup */
        -moz-border-radius-bottomleft: 8px;
        -moz-border-radius-bottomright: 8px;
        -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px;
        background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 60%, #F7F8FB 95%, #EEF1F7);
        /* webkit specific markup */
        -webkit-border-bottom-left-radius: 8px;
        -webkit-border-bottom-right-radius: 8px;
        -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15);
        background-image: -webkit-gradient(linear,center top,center bottom,from(#FFFFFF), color-stop(0.6,#FFFFFF), color-stop(0.60,#FFFFFF), color-stop(0.95,#F7F8FB), to(#EEF1F7));
}

dl.reflist dt {
        padding: 5px;
}

dl.reflist dd {
        margin: 0px 0px 10px 0px;
        padding: 5px;
}

.paramkey {
	text-align: right;
}

.paramtype {
	white-space: nowrap;
}

.paramname {
	color: #602020;
	white-space: nowrap;
}
.paramname em {
	font-style: normal;
}

.params, .retval, .exception, .tparams {
        border-spacing: 6px 2px;
}       

.params .paramname, .retval .paramname {
        font-weight: bold;
        vertical-align: top;
}
        
.params .paramtype {
        font-style: italic;
        vertical-align: top;
}       
        
.params .paramdir {
        font-family: "courier new",courier,monospace;
        vertical-align: top;
}




/* @end */

/* @group Directory (tree) */

/* for the tree view */

.ftvtree {
	font-family: sans-serif;
	margin: 0px;
}

/* these are for tree view when used as main index */

.directory {
	font-size: 9pt;
	font-weight: bold;
	margin: 5px;
}

.directory h3 {
	margin: 0px;
	margin-top: 1em;
	font-size: 11pt;
}

/*
The following two styles can be used to replace the root node title
with an image of your choice.  Simply uncomment the next two styles,
specify the name of your image and be sure to set 'height' to the
proper pixel height of your image.
*/

/*
.directory h3.swap {
	height: 61px;
	background-repeat: no-repeat;
	background-image: url("yourimage.gif");
}
.directory h3.swap span {
	display: none;
}
*/

.directory > h3 {
	margin-top: 0;
}

.directory p {
	margin: 0px;
	white-space: nowrap;
}

.directory div {
	display: none;
	margin: 0px;
}

.directory img {
	vertical-align: -30%;
}

/* these are for tree view when not used as main index */

.directory-alt {
	font-size: 100%;
	font-weight: bold;
}

.directory-alt h3 {
	margin: 0px;
	margin-top: 1em;
	font-size: 11pt;
}

.directory-alt > h3 {
	margin-top: 0;
}

.directory-alt p {
	margin: 0px;
	white-space: nowrap;
}

.directory-alt div {
	display: none;
	margin: 0px;
}

.directory-alt img {
	vertical-align: -30%;
}

/* @end */

div.dynheader {
        margin-top: 8px;
}

address {
	font-style: normal;
	color: #2A3D61;
}

table.doxtable {
	border-collapse:collapse;
}

table.doxtable td, table.doxtable th {
	border: 1px solid #2D4068;
	padding: 3px 7px 2px;
}

table.doxtable th {
	background-color: #374F7F;
	color: #FFFFFF;
	font-size: 110%;
	padding-bottom: 4px;
	padding-top: 5px;
	text-align:left;
}

table.fieldtable {
        width: 100%;
        margin-bottom: 10px;
        border: 1px solid #A8B8D9;
        border-spacing: 0px;
        -moz-border-radius: 4px;
        -webkit-border-radius: 4px;
        border-radius: 4px;
        -moz-box-shadow: rgba(0, 0, 0, 0.15) 2px 2px 2px;
        -webkit-box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15);
        box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15);
}

.fieldtable td, .fieldtable th {
        padding: 3px 7px 2px;
}

.fieldtable td.fieldtype, .fieldtable td.fieldname {
        white-space: nowrap;
        border-right: 1px solid #A8B8D9;
        border-bottom: 1px solid #A8B8D9;
        vertical-align: top;
}

.fieldtable td.fielddoc {
        border-bottom: 1px solid #A8B8D9;
        width: 100%;
}

.fieldtable tr:last-child td {
        border-bottom: none;
}

.fieldtable th {
        background-image:url('nav_f.png');
        background-repeat:repeat-x;
        background-color: #E2E8F2;
        font-size: 90%;
        color: #253555;
        padding-bottom: 4px;
        padding-top: 5px;
        text-align:left;
        -moz-border-radius-topleft: 4px;
        -moz-border-radius-topright: 4px;
        -webkit-border-top-left-radius: 4px;
        -webkit-border-top-right-radius: 4px;
        border-top-left-radius: 4px;
        border-top-right-radius: 4px;
        border-bottom: 1px solid #A8B8D9;
}


.tabsearch {
	top: 0px;
	left: 10px;
	height: 36px;
	background-image: url('tab_b.png');
	z-index: 101;
	overflow: hidden;
	font-size: 13px;
}

.navpath ul
{
	font-size: 11px;
	background-image:url('tab_b.png');
	background-repeat:repeat-x;
	height:30px;
	line-height:30px;
	color:#8AA0CC;
	border:solid 1px #C2CDE4;
	overflow:hidden;
	margin:0px;
	padding:0px;
}

.navpath li
{
	list-style-type:none;
	float:left;
	padding-left:10px;
	padding-right:15px;
	background-image:url('bc_s.png');
	background-repeat:no-repeat;
	background-position:right;
	color:#364D7C;
}

.navpath li.navelem a
{
	height:32px;
	display:block;
	text-decoration: none;
	outline: none;
}

.navpath li.navelem a:hover
{
	color:#6884BD;
}

.navpath li.footer
{
        list-style-type:none;
        float:right;
        padding-left:10px;
        padding-right:15px;
        background-image:none;
        background-repeat:no-repeat;
        background-position:right;
        color:#364D7C;
        font-size: 8pt;
}


div.summary
{
	float: right;
	font-size: 8pt;
	padding-right: 5px;
	width: 50%;
	text-align: right;
}       

div.summary a
{
	white-space: nowrap;
}

div.ingroups
{
	margin-left: 5px;
	font-size: 8pt;
	padding-left: 5px;
	width: 50%;
	text-align: left;
}

div.ingroups a
{
	white-space: nowrap;
}

div.header
{
        background-image:url('nav_h.png');
        background-repeat:repeat-x;
	background-color: #F9FAFC;
	margin:  0px;
	border-bottom: 1px solid #C4CFE5;
}

div.headertitle
{
	padding: 5px 5px 5px 7px;
}

dl
{
        padding: 0 0 0 10px;
}

dl.note, dl.warning, dl.attention, dl.pre, dl.post, dl.invariant, dl.deprecated, dl.todo, dl.test, dl.bug
{
        border-left:4px solid;
        padding: 0 0 0 6px;
}

dl.note
{
        border-color: #D0C000;
}

dl.warning, dl.attention
{
        border-color: #FF0000;
}

dl.pre, dl.post, dl.invariant
{
        border-color: #00D000;
}

dl.deprecated
{
        border-color: #505050;
}

dl.todo
{
        border-color: #00C0E0;
}

dl.test
{
        border-color: #3030E0;
}

dl.bug
{
        border-color: #C08050;
}

#projectlogo
{
	text-align: center;
	vertical-align: bottom;
	border-collapse: separate;
}
 
#projectlogo img
{ 
	border: 0px none;
}
 
#projectname
{
	font: 300% Tahoma, Arial,sans-serif;
	margin: 0px;
	padding: 2px 0px;
}
    
#projectbrief
{
	font: 120% Tahoma, Arial,sans-serif;
	margin: 0px;
	padding: 0px;
}

#projectnumber
{
	font: 50% Tahoma, Arial,sans-serif;
	margin: 0px;
	padding: 0px;
}

#titlearea
{
	padding: 0px;
	margin: 0px;
	width: 100%;
	border-bottom: 1px solid #5373B4;
}

.image
{
        text-align: center;
}

.dotgraph
{
        text-align: center;
}

.mscgraph
{
        text-align: center;
}

.caption
{
	font-weight: bold;
}

div.zoom
{
	border: 1px solid #90A5CE;
}

dl.citelist {
        margin-bottom:50px;
}

dl.citelist dt {
        color:#334975;
        float:left;
        font-weight:bold;
        margin-right:10px;
        padding:5px;
}

dl.citelist dd {
        margin:2px 0;
        padding:5px 0;
}

@media print
{
  #top { display: none; }
  #side-nav { display: none; }
  #nav-path { display: none; }
  body { overflow:visible; }
  h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
  .summary { display: none; }
  .memitem { page-break-inside: avoid; }
  #doc-content
  {
    margin-left:0 !important;
    height:auto !important;
    width:auto !important;
    overflow:inherit;
    display:inline;
  }
  pre.fragment
  {
    overflow: visible;
    text-wrap: unrestricted;
    white-space: -moz-pre-wrap; /* Moz */
    white-space: -pre-wrap; /* Opera 4-6 */
    white-space: -o-pre-wrap; /* Opera 7 */
    white-space: pre-wrap; /* CSS3  */
    word-wrap: break-word; /* IE 5.5+ */
  }
}

# Doxyfile 1.8.0

# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
#       TAG = value [value, ...]
# For lists items can also be appended using:
#       TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ")

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------

# This tag specifies the encoding used for all characters in the config file 
# that follow. The default is UTF-8 which is also the encoding used for all 
# text before the first occurrence of this tag. Doxygen uses libiconv (or the 
# iconv built into libc) for the transcoding. See 
# http://www.gnu.org/software/libiconv for the list of possible encodings.

DOXYFILE_ENCODING      = UTF-8

# The PROJECT_NAME tag is a single word (or sequence of words) that should 
# identify the project. Note that if you do not use Doxywizard you need 
# to put quotes around the project name if it contains spaces.

PROJECT_NAME           = Minx

# The PROJECT_NUMBER tag can be used to enter a project or revision number. 
# This could be handy for archiving the generated documentation or 
# if some version control system is used.

PROJECT_NUMBER         = 

# Using the PROJECT_BRIEF tag one can provide an optional one line description 
# for a project that appears at the top of each page and should give viewer 
# a quick idea about the purpose of the project. Keep the description short.

PROJECT_BRIEF          = "API Docs"

# With the PROJECT_LOGO tag one can specify an logo or icon that is 
# included in the documentation. The maximum height of the logo should not 
# exceed 55 pixels and the maximum width should not exceed 200 pixels. 
# Doxygen will copy the logo to the output directory.

PROJECT_LOGO           = 

# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
# base path where the generated documentation will be put. 
# If a relative path is entered, it will be relative to the location 
# where doxygen was started. If left blank the current directory will be used.

OUTPUT_DIRECTORY = @CMAKE_SOURCE_DIR@/api

# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
# 4096 sub-directories (in 2 levels) under the output directory of each output 
# format and will distribute the generated files over these directories. 
# Enabling this option can be useful when feeding doxygen a huge amount of 
# source files, where putting all generated files in the same directory would 
# otherwise cause performance problems for the file system.

CREATE_SUBDIRS         = NO

# The OUTPUT_LANGUAGE tag is used to specify the language in which all 
# documentation generated by doxygen is written. Doxygen will use this 
# information to generate all constant output in the proper language. 
# The default language is English, other supported languages are: 
# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, 
# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, 
# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English 
# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, 
# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, 
# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.

OUTPUT_LANGUAGE        = English

# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will 
# include brief member descriptions after the members that are listed in 
# the file and class documentation (similar to JavaDoc). 
# Set to NO to disable this.

BRIEF_MEMBER_DESC      = YES

# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend 
# the brief description of a member or function before the detailed description. 
# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the 
# brief descriptions will be completely suppressed.

REPEAT_BRIEF           = YES

# This tag implements a quasi-intelligent brief description abbreviator 
# that is used to form the text in various listings. Each string 
# in this list, if found as the leading text of the brief description, will be 
# stripped from the text and the result after processing the whole list, is 
# used as the annotated text. Otherwise, the brief description is used as-is. 
# If left blank, the following values are used ("$name" is automatically 
# replaced with the name of the entity): "The $name class" "The $name widget" 
# "The $name file" "is" "provides" "specifies" "contains" 
# "represents" "a" "an" "the"

ABBREVIATE_BRIEF       = "The $name class" \
                         "The $name widget" \
                         "The $name file" \
                         is \
                         provides \
                         specifies \
                         contains \
                         represents \
                         a \
                         an \
                         the

# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then 
# Doxygen will generate a detailed section even if there is only a brief 
# description.

ALWAYS_DETAILED_SEC    = NO

# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all 
# inherited members of a class in the documentation of that class as if those 
# members were ordinary class members. Constructors, destructors and assignment 
# operators of the base classes will not be shown.

INLINE_INHERITED_MEMB  = NO

# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full 
# path before files name in the file list and in the header files. If set 
# to NO the shortest path that makes the file name unique will be used.

FULL_PATH_NAMES        = YES

# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag 
# can be used to strip a user-defined part of the path. Stripping is 
# only done if one of the specified strings matches the left-hand part of 
# the path. The tag can be used to show relative paths in the file list. 
# If left blank the directory from which doxygen is run is used as the 
# path to strip.

STRIP_FROM_PATH        = 

# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
# the path mentioned in the documentation of a class, which tells 
# the reader which header file to include in order to use a class. 
# If left blank only the name of the header file containing the class 
# definition is used. Otherwise one should specify the include paths that 
# are normally passed to the compiler using the -I flag.

STRIP_FROM_INC_PATH    = 

# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
# (but less readable) file names. This can be useful if your file system 
# doesn't support long names like on DOS, Mac, or CD-ROM.

SHORT_NAMES            = NO

# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen 
# will interpret the first line (until the first dot) of a JavaDoc-style 
# comment as the brief description. If set to NO, the JavaDoc 
# comments will behave just like regular Qt-style comments 
# (thus requiring an explicit @brief command for a brief description.)

JAVADOC_AUTOBRIEF      = NO

# If the QT_AUTOBRIEF tag is set to YES then Doxygen will 
# interpret the first line (until the first dot) of a Qt-style 
# comment as the brief description. If set to NO, the comments 
# will behave just like regular Qt-style comments (thus requiring 
# an explicit \brief command for a brief description.)

QT_AUTOBRIEF           = NO

# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen 
# treat a multi-line C++ special comment block (i.e. a block of //! or /// 
# comments) as a brief description. This used to be the default behaviour. 
# The new default is to treat a multi-line C++ comment block as a detailed 
# description. Set this tag to YES if you prefer the old behaviour instead.

MULTILINE_CPP_IS_BRIEF = NO

# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented 
# member inherits the documentation from any documented member that it 
# re-implements.

INHERIT_DOCS           = YES

# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce 
# a new page for each member. If set to NO, the documentation of a member will 
# be part of the file/class/namespace that contains it.

SEPARATE_MEMBER_PAGES  = NO

# The TAB_SIZE tag can be used to set the number of spaces in a tab. 
# Doxygen uses this value to replace tabs by spaces in code fragments.

TAB_SIZE               = 8

# This tag can be used to specify a number of aliases that acts 
# as commands in the documentation. An alias has the form "name=value". 
# For example adding "sideeffect=\par Side Effects:\n" will allow you to 
# put the command \sideeffect (or @sideeffect) in the documentation, which 
# will result in a user-defined paragraph with heading "Side Effects:". 
# You can put \n's in the value part of an alias to insert newlines.

ALIASES = boostpylink="<a href=\"http://www.boost.org/libs/python/doc/\">Boost.Python</a>"

# This tag can be used to specify a number of word-keyword mappings (TCL only). 
# A mapping has the form "name=value". For example adding 
# "class=itcl::class" will allow you to use the command class in the 
# itcl::class meaning.

TCL_SUBST              = 

# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C 
# sources only. Doxygen will then generate output that is more tailored for C. 
# For instance, some of the names that are used will be different. The list 
# of all members will be omitted, etc.

OPTIMIZE_OUTPUT_FOR_C  = NO

# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java 
# sources only. Doxygen will then generate output that is more tailored for 
# Java. For instance, namespaces will be presented as packages, qualified 
# scopes will look different, etc.

OPTIMIZE_OUTPUT_JAVA   = NO

# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran 
# sources only. Doxygen will then generate output that is more tailored for 
# Fortran.

OPTIMIZE_FOR_FORTRAN   = NO

# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL 
# sources. Doxygen will then generate output that is tailored for 
# VHDL.

OPTIMIZE_OUTPUT_VHDL   = NO

# Doxygen selects the parser to use depending on the extension of the files it 
# parses. With this tag you can assign which parser to use for a given extension. 
# Doxygen has a built-in mapping, but you can override or extend it using this 
# tag. The format is ext=language, where ext is a file extension, and language 
# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, 
# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make 
# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C 
# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions 
# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.

EXTENSION_MAPPING      = 

# If MARKDOWN_SUPPORT is enabled (the default) then doxygen pre-processes all 
# comments according to the Markdown format, which allows for more readable 
# documentation. See http://daringfireball.net/projects/markdown/ for details. 
# The output of markdown processing is further processed by doxygen, so you 
# can mix doxygen, HTML, and XML commands with Markdown formatting. 
# Disable only in case of backward compatibilities issues.

MARKDOWN_SUPPORT = NO

# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want 
# to include (a tag file for) the STL sources as input, then you should 
# set this tag to YES in order to let doxygen match functions declarations and 
# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. 
# func(std::string) {}). This also makes the inheritance and collaboration 
# diagrams that involve STL classes more complete and accurate.

BUILTIN_STL_SUPPORT    = NO

# If you use Microsoft's C++/CLI language, you should set this option to YES to 
# enable parsing support.

CPP_CLI_SUPPORT        = NO

# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. 
# Doxygen will parse them like normal C++ but will assume all classes use public 
# instead of private inheritance when no explicit protection keyword is present.

SIP_SUPPORT            = NO

# For Microsoft's IDL there are propget and propput attributes to indicate getter 
# and setter methods for a property. Setting this option to YES (the default) 
# will make doxygen replace the get and set methods by a property in the 
# documentation. This will only work if the methods are indeed getting or 
# setting a simple type. If this is not the case, or you want to show the 
# methods anyway, you should set this option to NO.

IDL_PROPERTY_SUPPORT   = YES

# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC 
# tag is set to YES, then doxygen will reuse the documentation of the first 
# member in the group (if any) for the other members of the group. By default 
# all members of a group must be documented explicitly.

DISTRIBUTE_GROUP_DOC   = YES

# Set the SUBGROUPING tag to YES (the default) to allow class member groups of 
# the same type (for instance a group of public functions) to be put as a 
# subgroup of that type (e.g. under the Public Functions section). Set it to 
# NO to prevent subgrouping. Alternatively, this can be done per class using 
# the \nosubgrouping command.

SUBGROUPING            = YES

# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and 
# unions are shown inside the group in which they are included (e.g. using 
# @ingroup) instead of on a separate page (for HTML and Man pages) or 
# section (for LaTeX and RTF).

INLINE_GROUPED_CLASSES = NO

# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and 
# unions with only public data fields will be shown inline in the documentation 
# of the scope in which they are defined (i.e. file, namespace, or group 
# documentation), provided this scope is documented. If set to NO (the default), 
# structs, classes, and unions are shown on a separate page (for HTML and Man 
# pages) or section (for LaTeX and RTF).

INLINE_SIMPLE_STRUCTS  = NO

# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum 
# is documented as struct, union, or enum with the name of the typedef. So 
# typedef struct TypeS {} TypeT, will appear in the documentation as a struct 
# with name TypeT. When disabled the typedef will appear as a member of a file, 
# namespace, or class. And the struct will be named TypeS. This can typically 
# be useful for C code in case the coding convention dictates that all compound 
# types are typedef'ed and only the typedef is referenced, never the tag name.

TYPEDEF_HIDES_STRUCT   = NO

# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to 
# determine which symbols to keep in memory and which to flush to disk. 
# When the cache is full, less often used symbols will be written to disk. 
# For small to medium size projects (<1000 input files) the default value is 
# probably good enough. For larger projects a too small cache size can cause 
# doxygen to be busy swapping symbols to and from disk most of the time 
# causing a significant performance penalty. 
# If the system has enough physical memory increasing the cache will improve the 
# performance by keeping more symbols in memory. Note that the value works on 
# a logarithmic scale so increasing the size by one will roughly double the 
# memory usage. The cache size is given by this formula: 
# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, 
# corresponding to a cache size of 2^16 = 65536 symbols.

SYMBOL_CACHE_SIZE      = 0

# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be 
# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given 
# their name and scope. Since this can be an expensive process and often the 
# same symbol appear multiple times in the code, doxygen keeps a cache of 
# pre-resolved symbols. If the cache is too small doxygen will become slower. 
# If the cache is too large, memory is wasted. The cache size is given by this 
# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0, 
# corresponding to a cache size of 2^16 = 65536 symbols.

LOOKUP_CACHE_SIZE      = 0

#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------

# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in 
# documentation are documented, even if no documentation was available. 
# Private class members and static file members will be hidden unless 
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES

EXTRACT_ALL            = NO

# If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
# will be included in the documentation.

EXTRACT_PRIVATE        = NO

# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
# scope will be included in the documentation.

EXTRACT_PACKAGE        = NO

# If the EXTRACT_STATIC tag is set to YES all static members of a file 
# will be included in the documentation.

EXTRACT_STATIC         = NO

# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) 
# defined locally in source files will be included in the documentation. 
# If set to NO only classes defined in header files are included.

EXTRACT_LOCAL_CLASSES  = NO

# This flag is only useful for Objective-C code. When set to YES local 
# methods, which are defined in the implementation section but not in 
# the interface are included in the documentation. 
# If set to NO (the default) only methods in the interface are included.

EXTRACT_LOCAL_METHODS  = NO

# If this flag is set to YES, the members of anonymous namespaces will be 
# extracted and appear in the documentation as a namespace called 
# 'anonymous_namespace{file}', where file will be replaced with the base 
# name of the file that contains the anonymous namespace. By default 
# anonymous namespaces are hidden.

EXTRACT_ANON_NSPACES   = NO

# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all 
# undocumented members of documented classes, files or namespaces. 
# If set to NO (the default) these members will be included in the 
# various overviews, but no documentation section is generated. 
# This option has no effect if EXTRACT_ALL is enabled.

HIDE_UNDOC_MEMBERS     = YES

# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all 
# undocumented classes that are normally visible in the class hierarchy. 
# If set to NO (the default) these classes will be included in the various 
# overviews. This option has no effect if EXTRACT_ALL is enabled.

HIDE_UNDOC_CLASSES     = YES

# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all 
# friend (class|struct|union) declarations. 
# If set to NO (the default) these declarations will be included in the 
# documentation.

HIDE_FRIEND_COMPOUNDS  = YES

# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any 
# documentation blocks found inside the body of a function. 
# If set to NO (the default) these blocks will be appended to the 
# function's detailed documentation block.

HIDE_IN_BODY_DOCS      = NO

# The INTERNAL_DOCS tag determines if documentation 
# that is typed after a \internal command is included. If the tag is set 
# to NO (the default) then the documentation will be excluded. 
# Set it to YES to include the internal documentation.

INTERNAL_DOCS          = NO

# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate 
# file names in lower-case letters. If set to YES upper-case letters are also 
# allowed. This is useful if you have classes or files whose names only differ 
# in case and if your file system supports case sensitive file names. Windows 
# and Mac users are advised to set this option to NO.

CASE_SENSE_NAMES       = NO

# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen 
# will show members with their full class and namespace scopes in the 
# documentation. If set to YES the scope will be hidden.

HIDE_SCOPE_NAMES       = NO

# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen 
# will put a list of the files that are included by a file in the documentation 
# of that file.

SHOW_INCLUDE_FILES     = YES

# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen 
# will list include files with double quotes in the documentation 
# rather than with sharp brackets.

FORCE_LOCAL_INCLUDES   = NO

# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] 
# is inserted in the documentation for inline members.

INLINE_INFO            = YES

# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen 
# will sort the (detailed) documentation of file and class members 
# alphabetically by member name. If set to NO the members will appear in 
# declaration order.

SORT_MEMBER_DOCS       = YES

# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the 
# brief documentation of file, namespace and class members alphabetically 
# by member name. If set to NO (the default) the members will appear in 
# declaration order.

SORT_BRIEF_DOCS        = NO

# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen 
# will sort the (brief and detailed) documentation of class members so that 
# constructors and destructors are listed first. If set to NO (the default) 
# the constructors will appear in the respective orders defined by 
# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. 
# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO 
# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO.

SORT_MEMBERS_CTORS_1ST = NO

# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the 
# hierarchy of group names into alphabetical order. If set to NO (the default) 
# the group names will appear in their defined order.

SORT_GROUP_NAMES       = NO

# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be 
# sorted by fully-qualified names, including namespaces. If set to 
# NO (the default), the class list will be sorted only by class name, 
# not including the namespace part. 
# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. 
# Note: This option applies only to the class list, not to the 
# alphabetical list.

SORT_BY_SCOPE_NAME     = NO

# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to 
# do proper type resolution of all parameters of a function it will reject a 
# match between the prototype and the implementation of a member function even 
# if there is only one candidate or it is obvious which candidate to choose 
# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen 
# will still accept a match between prototype and implementation in such cases.

STRICT_PROTO_MATCHING  = NO

# The GENERATE_TODOLIST tag can be used to enable (YES) or 
# disable (NO) the todo list. This list is created by putting \todo 
# commands in the documentation.

GENERATE_TODOLIST      = YES

# The GENERATE_TESTLIST tag can be used to enable (YES) or 
# disable (NO) the test list. This list is created by putting \test 
# commands in the documentation.

GENERATE_TESTLIST      = YES

# The GENERATE_BUGLIST tag can be used to enable (YES) or 
# disable (NO) the bug list. This list is created by putting \bug 
# commands in the documentation.

GENERATE_BUGLIST       = YES

# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or 
# disable (NO) the deprecated list. This list is created by putting 
# \deprecated commands in the documentation.

GENERATE_DEPRECATEDLIST= YES

# The ENABLED_SECTIONS tag can be used to enable conditional 
# documentation sections, marked by \if sectionname ... \endif.

ENABLED_SECTIONS       = 

# The MAX_INITIALIZER_LINES tag determines the maximum number of lines 
# the initial value of a variable or macro consists of for it to appear in 
# the documentation. If the initializer consists of more lines than specified 
# here it will be hidden. Use a value of 0 to hide initializers completely. 
# The appearance of the initializer of individual variables and macros in the 
# documentation can be controlled using \showinitializer or \hideinitializer 
# command in the documentation regardless of this setting.

MAX_INITIALIZER_LINES  = 30

# Set the SHOW_USED_FILES tag to NO to disable the list of files generated 
# at the bottom of the documentation of classes and structs. If set to YES the 
# list will mention the files that were used to generate the documentation.

SHOW_USED_FILES = NO

# If the sources in your project are distributed over multiple directories 
# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy 
# in the documentation. The default is NO.

SHOW_DIRECTORIES       = NO

# Set the SHOW_FILES tag to NO to disable the generation of the Files page. 
# This will remove the Files entry from the Quick Index and from the 
# Folder Tree View (if specified). The default is YES.

SHOW_FILES = NO

# Set the SHOW_NAMESPACES tag to NO to disable the generation of the 
# Namespaces page.  This will remove the Namespaces entry from the Quick Index 
# and from the Folder Tree View (if specified). The default is YES.

SHOW_NAMESPACES = NO

# The FILE_VERSION_FILTER tag can be used to specify a program or script that 
# doxygen should invoke to get the current version for each file (typically from 
# the version control system). Doxygen will invoke the program by executing (via 
# popen()) the command <command> <input-file>, where <command> is the value of 
# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file 
# provided by doxygen. Whatever the program writes to standard output 
# is used as the file version. See the manual for examples.

FILE_VERSION_FILTER    = 

# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed 
# by doxygen. The layout file controls the global structure of the generated 
# output files in an output format independent way. The create the layout file 
# that represents doxygen's defaults, run doxygen with the -l option. 
# You can optionally specify a file name after the option, if omitted 
# DoxygenLayout.xml will be used as the name of the layout file.

#LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/layout.xml
LAYOUT_FILE = 

# The CITE_BIB_FILES tag can be used to specify one or more bib files 
# containing the references data. This must be a list of .bib files. The 
# .bib extension is automatically appended if omitted. Using this command 
# requires the bibtex tool to be installed. See also 
# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style 
# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this 
# feature you need bibtex and perl available in the search path.

CITE_BIB_FILES         = 

#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------

# The QUIET tag can be used to turn on/off the messages that are generated 
# by doxygen. Possible values are YES and NO. If left blank NO is used.

QUIET                  = YES

# The WARNINGS tag can be used to turn on/off the warning messages that are 
# generated by doxygen. Possible values are YES and NO. If left blank 
# NO is used.

WARNINGS               = NO

# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings 
# for undocumented members. If EXTRACT_ALL is set to YES then this flag will 
# automatically be disabled.

WARN_IF_UNDOCUMENTED   = NO

# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for 
# potential errors in the documentation, such as not documenting some 
# parameters in a documented function, or documenting parameters that 
# don't exist or using markup commands wrongly.

WARN_IF_DOC_ERROR      = YES

# The WARN_NO_PARAMDOC option can be enabled to get warnings for 
# functions that are documented, but have no documentation for their parameters 
# or return value. If set to NO (the default) doxygen will only warn about 
# wrong or incomplete parameter documentation, but not about the absence of 
# documentation.

WARN_NO_PARAMDOC       = NO

# The WARN_FORMAT tag determines the format of the warning messages that 
# doxygen can produce. The string should contain the $file, $line, and $text 
# tags, which will be replaced by the file and line number from which the 
# warning originated and the warning text. Optionally the format may contain 
# $version, which will be replaced by the version of the file (if it could 
# be obtained via FILE_VERSION_FILTER)

WARN_FORMAT            = "$file:$line: $text"

# The WARN_LOGFILE tag can be used to specify a file to which warning 
# and error messages should be written. If left blank the output is written 
# to stderr.

WARN_LOGFILE           = 

#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------

# The INPUT tag can be used to specify the files and/or directories that contain 
# documented source files. You may enter file names like "myfile.cpp" or 
# directories like "/usr/src/myproject". Separate the files or directories 
# with spaces.

INPUT = @CMAKE_SOURCE_DIR@/minxlib  \
        @CMAKE_SOURCE_DIR@/core     \
        @CMAKE_SOURCE_DIR@/layout   \
        @CMAKE_SOURCE_DIR@/dox

# This tag can be used to specify the character encoding of the source files 
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
# also the default input encoding. Doxygen uses libiconv (or the iconv built 
# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for 
# the list of possible encodings.

INPUT_ENCODING         = UTF-8

# If the value of the INPUT tag contains directories, you can use the 
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
# and *.h) to filter out the source-files in the directories. If left 
# blank the following patterns are tested: 
# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh 
# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py 
# *.f90 *.f *.for *.vhd *.vhdl

FILE_PATTERNS          = *.hh \
                         *.py

# The RECURSIVE tag can be used to turn specify whether or not subdirectories 
# should be searched for input files as well. Possible values are YES and NO. 
# If left blank NO is used.

RECURSIVE              = NO

# The EXCLUDE tag can be used to specify files and/or directories that should be 
# excluded from the INPUT source files. This way you can easily exclude a 
# subdirectory from a directory tree whose root is specified with the INPUT tag. 
# Note that relative paths are relative to the directory from which doxygen is 
# run.

EXCLUDE                = __init__.py

# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or 
# directories that are symbolic links (a Unix file system feature) are excluded 
# from the input.

EXCLUDE_SYMLINKS       = NO

# If the value of the INPUT tag contains directories, you can use the 
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude 
# certain files from those directories. Note that the wildcards are matched 
# against the file with absolute path, so to exclude all test directories 
# for example use the pattern */test/*

EXCLUDE_PATTERNS       = 

# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names 
# (namespaces, classes, functions, etc.) that should be excluded from the 
# output. The symbol name can be a fully qualified name, a word, or if the 
# wildcard * is used, a substring. Examples: ANamespace, AClass, 
# AClass::ANamespace, ANamespace::*Test

EXCLUDE_SYMBOLS        = 

# The EXAMPLE_PATH tag can be used to specify one or more files or 
# directories that contain example code fragments that are included (see 
# the \include command).

EXAMPLE_PATH           = 

# If the value of the EXAMPLE_PATH tag contains directories, you can use the 
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
# and *.h) to filter out the source-files in the directories. If left 
# blank all files are included.

EXAMPLE_PATTERNS       = *

# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be 
# searched for input files to be used with the \include or \dontinclude 
# commands irrespective of the value of the RECURSIVE tag. 
# Possible values are YES and NO. If left blank NO is used.

EXAMPLE_RECURSIVE      = NO

# The IMAGE_PATH tag can be used to specify one or more files or 
# directories that contain image that are included in the documentation (see 
# the \image command).

IMAGE_PATH             = 

# The INPUT_FILTER tag can be used to specify a program that doxygen should 
# invoke to filter for each input file. Doxygen will invoke the filter program 
# by executing (via popen()) the command <filter> <input-file>, where <filter> 
# is the value of the INPUT_FILTER tag, and <input-file> is the name of an 
# input file. Doxygen will then use the output that the filter program writes 
# to standard output.  If FILTER_PATTERNS is specified, this tag will be 
# ignored.

INPUT_FILTER           = 

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern 
# basis.  Doxygen will compare the file name with each pattern and apply the 
# filter if there is a match.  The filters are a list of the form: 
# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further 
# info on how filters are used. If FILTER_PATTERNS is empty or if 
# non of the patterns match the file name, INPUT_FILTER is applied.

FILTER_PATTERNS = *.py=@CMAKE_CURRENT_SOURCE_DIR@/doxypy --autobrief

# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using 
# INPUT_FILTER) will be used to filter the input files when producing source 
# files to browse (i.e. when SOURCE_BROWSER is set to YES).

FILTER_SOURCE_FILES    = NO

# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file 
# pattern. A pattern will override the setting for FILTER_PATTERN (if any) 
# and it is also possible to disable source filtering for a specific pattern 
# using *.ext= (so without naming a filter). This option only has effect when 
# FILTER_SOURCE_FILES is enabled.

FILTER_SOURCE_PATTERNS = 

#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------

# If the SOURCE_BROWSER tag is set to YES then a list of source files will 
# be generated. Documented entities will be cross-referenced with these sources. 
# Note: To get rid of all source code in the generated output, make sure also 
# VERBATIM_HEADERS is set to NO.

SOURCE_BROWSER         = NO

# Setting the INLINE_SOURCES tag to YES will include the body 
# of functions and classes directly in the documentation.

INLINE_SOURCES         = NO

# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct 
# doxygen to hide any special comment blocks from generated source code 
# fragments. Normal C and C++ comments will always remain visible.

STRIP_CODE_COMMENTS    = YES

# If the REFERENCED_BY_RELATION tag is set to YES 
# then for each documented function all documented 
# functions referencing it will be listed.

REFERENCED_BY_RELATION = NO

# If the REFERENCES_RELATION tag is set to YES 
# then for each documented function all documented entities 
# called/used by that function will be listed.

REFERENCES_RELATION    = NO

# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) 
# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from 
# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will 
# link to the source code.  Otherwise they will link to the documentation.

REFERENCES_LINK_SOURCE = YES

# If the USE_HTAGS tag is set to YES then the references to source code 
# will point to the HTML generated by the htags(1) tool instead of doxygen 
# built-in source browser. The htags tool is part of GNU's global source 
# tagging system (see http://www.gnu.org/software/global/global.html). You 
# will need version 4.8.6 or higher.

USE_HTAGS              = NO

# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen 
# will generate a verbatim copy of the header file for each class for 
# which an include is specified. Set to NO to disable this.

VERBATIM_HEADERS = NO

#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------

# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index 
# of all compounds will be generated. Enable this if the project 
# contains a lot of classes, structs, unions or interfaces.

ALPHABETICAL_INDEX     = YES

# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then 
# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns 
# in which this list will be split (can be a number in the range [1..20])

COLS_IN_ALPHA_INDEX    = 5

# In case all classes in a project start with a common prefix, all 
# classes will be put under the same header in the alphabetical index. 
# The IGNORE_PREFIX tag can be used to specify one or more prefixes that 
# should be ignored while generating the index headers.

IGNORE_PREFIX          = 

#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------

# If the GENERATE_HTML tag is set to YES (the default) Doxygen will 
# generate HTML output.

GENERATE_HTML          = YES

# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank `html' will be used as the default path.

HTML_OUTPUT = .

# The HTML_FILE_EXTENSION tag can be used to specify the file extension for 
# each generated HTML page (for example: .htm,.php,.asp). If it is left blank 
# doxygen will generate files with .html extension.

HTML_FILE_EXTENSION    = .html

# The HTML_HEADER tag can be used to specify a personal HTML header for 
# each generated HTML page. If it is left blank doxygen will generate a 
# standard header. Note that when using a custom header you are responsible  
# for the proper inclusion of any scripts and style sheets that doxygen 
# needs, which is dependent on the configuration options used. 
# It is advised to generate a default header using "doxygen -w html 
# header.html footer.html stylesheet.css YourConfigFile" and then modify 
# that header. Note that the header is subject to change so you typically 
# have to redo this when upgrading to a newer version of doxygen or when 
# changing the value of configuration settings such as GENERATE_TREEVIEW!

HTML_HEADER = @CMAKE_CURRENT_SOURCE_DIR@/header.html

# The HTML_FOOTER tag can be used to specify a personal HTML footer for 
# each generated HTML page. If it is left blank doxygen will generate a 
# standard footer.

HTML_FOOTER = @CMAKE_CURRENT_SOURCE_DIR@/footer.html

# The HTML_STYLESHEET tag can be used to specify a user-defined cascading 
# style sheet that is used by each HTML page. It can be used to 
# fine-tune the look of the HTML output. If the tag is left blank doxygen 
# will generate a default style sheet. Note that doxygen will try to copy 
# the style sheet file to the HTML output directory, so don't put your own 
# style sheet in the HTML output directory as well, or it will be erased!

HTML_STYLESHEET = @CMAKE_CURRENT_SOURCE_DIR@/dox.css

# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or 
# other source files which should be copied to the HTML output directory. Note 
# that these files will be copied to the base HTML output directory. Use the 
# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these 
# files. In the HTML_STYLESHEET file, use the file name only. Also note that 
# the files will be copied as-is; there are no commands or markers available.

HTML_EXTRA_FILES       = 

# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. 
# Doxygen will adjust the colors in the style sheet and background images 
# according to this color. Hue is specified as an angle on a colorwheel, 
# see http://en.wikipedia.org/wiki/Hue for more information. 
# For instance the value 0 represents red, 60 is yellow, 120 is green, 
# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. 
# The allowed range is 0 to 359.

HTML_COLORSTYLE_HUE    = 220

# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of 
# the colors in the HTML output. For a value of 0 the output will use 
# grayscales only. A value of 255 will produce the most vivid colors.

HTML_COLORSTYLE_SAT    = 100

# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to 
# the luminance component of the colors in the HTML output. Values below 
# 100 gradually make the output lighter, whereas values above 100 make 
# the output darker. The value divided by 100 is the actual gamma applied, 
# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, 
# and 100 does not change the gamma.

HTML_COLORSTYLE_GAMMA  = 80

# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML 
# page will contain the date and time when the page was generated. Setting 
# this to NO can help when comparing the output of multiple runs.

HTML_TIMESTAMP = NO

# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, 
# files or namespaces will be aligned in HTML using tables. If set to 
# NO a bullet list will be used.

HTML_ALIGN_MEMBERS     = YES

# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML 
# documentation will contain sections that can be hidden and shown after the 
# page has loaded. For this to work a browser that supports 
# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox 
# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).

HTML_DYNAMIC_SECTIONS  = NO

# If the GENERATE_DOCSET tag is set to YES, additional index files 
# will be generated that can be used as input for Apple's Xcode 3 
# integrated development environment, introduced with OSX 10.5 (Leopard). 
# To create a documentation set, doxygen will generate a Makefile in the 
# HTML output directory. Running make will produce the docset in that 
# directory and running "make install" will install the docset in 
# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find 
# it at startup. 
# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html 
# for more information.

GENERATE_DOCSET        = NO

# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the 
# feed. A documentation feed provides an umbrella under which multiple 
# documentation sets from a single provider (such as a company or product suite) 
# can be grouped.

DOCSET_FEEDNAME        = "Doxygen generated docs"

# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that 
# should uniquely identify the documentation set bundle. This should be a 
# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen 
# will append .docset to the name.

DOCSET_BUNDLE_ID       = org.doxygen.Project

# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify 
# the documentation publisher. This should be a reverse domain-name style 
# string, e.g. com.mycompany.MyDocSet.documentation.

DOCSET_PUBLISHER_ID    = org.doxygen.Publisher

# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher.

DOCSET_PUBLISHER_NAME  = Publisher

# If the GENERATE_HTMLHELP tag is set to YES, additional index files 
# will be generated that can be used as input for tools like the 
# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) 
# of the generated HTML documentation.

GENERATE_HTMLHELP      = NO

# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can 
# be used to specify the file name of the resulting .chm file. You 
# can add a path in front of the file if the result should not be 
# written to the html output directory.

CHM_FILE               = 

# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can 
# be used to specify the location (absolute path including file name) of 
# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run 
# the HTML help compiler on the generated index.hhp.

HHC_LOCATION           = 

# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag 
# controls if a separate .chi index file is generated (YES) or that 
# it should be included in the master .chm file (NO).

GENERATE_CHI           = NO

# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING 
# is used to encode HtmlHelp index (hhk), content (hhc) and project file 
# content.

CHM_INDEX_ENCODING     = 

# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag 
# controls whether a binary table of contents is generated (YES) or a 
# normal table of contents (NO) in the .chm file.

BINARY_TOC             = NO

# The TOC_EXPAND flag can be set to YES to add extra items for group members 
# to the contents of the HTML help documentation and to the tree view.

TOC_EXPAND             = NO

# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and 
# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated 
# that can be used as input for Qt's qhelpgenerator to generate a 
# Qt Compressed Help (.qch) of the generated HTML documentation.

GENERATE_QHP           = NO

# If the QHG_LOCATION tag is specified, the QCH_FILE tag can 
# be used to specify the file name of the resulting .qch file. 
# The path specified is relative to the HTML output folder.

QCH_FILE               = 

# The QHP_NAMESPACE tag specifies the namespace to use when generating 
# Qt Help Project output. For more information please see 
# http://doc.trolltech.com/qthelpproject.html#namespace

QHP_NAMESPACE          = org.doxygen.Project

# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating 
# Qt Help Project output. For more information please see 
# http://doc.trolltech.com/qthelpproject.html#virtual-folders

QHP_VIRTUAL_FOLDER     = doc

# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to 
# add. For more information please see 
# http://doc.trolltech.com/qthelpproject.html#custom-filters

QHP_CUST_FILTER_NAME   = 

# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the 
# custom filter to add. For more information please see 
# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> 
# Qt Help Project / Custom Filters</a>.

QHP_CUST_FILTER_ATTRS  = 

# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this 
# project's 
# filter section matches. 
# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> 
# Qt Help Project / Filter Attributes</a>.

QHP_SECT_FILTER_ATTRS  = 

# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can 
# be used to specify the location of Qt's qhelpgenerator. 
# If non-empty doxygen will try to run qhelpgenerator on the generated 
# .qhp file.

QHG_LOCATION           = 

# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files  
# will be generated, which together with the HTML files, form an Eclipse help 
# plugin. To install this plugin and make it available under the help contents 
# menu in Eclipse, the contents of the directory containing the HTML and XML 
# files needs to be copied into the plugins directory of eclipse. The name of 
# the directory within the plugins directory should be the same as 
# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before 
# the help appears.

GENERATE_ECLIPSEHELP   = NO

# A unique identifier for the eclipse help plugin. When installing the plugin 
# the directory name containing the HTML and XML files should also have 
# this name.

ECLIPSE_DOC_ID         = org.doxygen.Project

# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) 
# at top of each HTML page. The value NO (the default) enables the index and 
# the value YES disables it. Since the tabs have the same information as the 
# navigation tree you can set this option to NO if you already set 
# GENERATE_TREEVIEW to YES.

DISABLE_INDEX          = YES

# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index 
# structure should be generated to display hierarchical information. 
# If the tag value is set to YES, a side panel will be generated 
# containing a tree-like index structure (just like the one that 
# is generated for HTML Help). For this to work a browser that supports 
# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). 
# Windows users are probably better off using the HTML help feature. 
# Since the tree basically has the same information as the tab index you 
# could consider to set DISABLE_INDEX to NO when enabling this option.

GENERATE_TREEVIEW      = NO

# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values 
# (range [0,1..20]) that doxygen will group on one line in the generated HTML 
# documentation. Note that a value of 0 will completely suppress the enum 
# values from appearing in the overview section.

ENUM_VALUES_PER_LINE   = 4

# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, 
# and Class Hierarchy pages using a tree view instead of an ordered list.

USE_INLINE_TREES       = NO

# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 
# used to set the initial width (in pixels) of the frame in which the tree 
# is shown.

TREEVIEW_WIDTH         = 250

# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open 
# links to external symbols imported via tag files in a separate window.

EXT_LINKS_IN_WINDOW    = NO

# Use this tag to change the font size of Latex formulas included 
# as images in the HTML documentation. The default is 10. Note that 
# when you change the font size after a successful doxygen run you need 
# to manually remove any form_*.png images from the HTML output directory 
# to force them to be regenerated.

FORMULA_FONTSIZE       = 10

# Use the FORMULA_TRANPARENT tag to determine whether or not the images 
# generated for formulas are transparent PNGs. Transparent PNGs are 
# not supported properly for IE 6.0, but are supported on all modern browsers. 
# Note that when changing this option you need to delete any form_*.png files 
# in the HTML output before the changes have effect.

FORMULA_TRANSPARENT    = YES

# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax 
# (see http://www.mathjax.org) which uses client side Javascript for the 
# rendering instead of using prerendered bitmaps. Use this if you do not 
# have LaTeX installed or if you want to formulas look prettier in the HTML 
# output. When enabled you may also need to install MathJax separately and 
# configure the path to it using the MATHJAX_RELPATH option.

USE_MATHJAX            = NO

# When MathJax is enabled you need to specify the location relative to the 
# HTML output directory using the MATHJAX_RELPATH option. The destination 
# directory should contain the MathJax.js script. For instance, if the mathjax 
# directory is located at the same level as the HTML output directory, then 
# MATHJAX_RELPATH should be ../mathjax. The default value points to 
# the MathJax Content Delivery Network so you can quickly see the result without 
# installing MathJax.  However, it is strongly recommended to install a local 
# copy of MathJax from http://www.mathjax.org before deployment.

MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest

# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension 
# names that should be enabled during MathJax rendering.

MATHJAX_EXTENSIONS     = 

# When the SEARCHENGINE tag is enabled doxygen will generate a search box 
# for the HTML output. The underlying search engine uses javascript 
# and DHTML and should work on any modern browser. Note that when using 
# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets 
# (GENERATE_DOCSET) there is already a search function so this one should 
# typically be disabled. For large projects the javascript based search engine 
# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution.

SEARCHENGINE = NO

# When the SERVER_BASED_SEARCH tag is enabled the search engine will be 
# implemented using a PHP enabled web server instead of at the web client 
# using Javascript. Doxygen will generate the search PHP script and index 
# file to put on the web server. The advantage of the server 
# based approach is that it scales better to large projects and allows 
# full text search. The disadvantages are that it is more difficult to setup 
# and does not have live searching capabilities.

SERVER_BASED_SEARCH    = NO

#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------

# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will 
# generate Latex output.

GENERATE_LATEX         = NO

# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank `latex' will be used as the default path.

LATEX_OUTPUT           = latex

# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be 
# invoked. If left blank `latex' will be used as the default command name. 
# Note that when enabling USE_PDFLATEX this option is only used for 
# generating bitmaps for formulas in the HTML output, but not in the 
# Makefile that is written to the output directory.

LATEX_CMD_NAME         = latex

# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to 
# generate index for LaTeX. If left blank `makeindex' will be used as the 
# default command name.

MAKEINDEX_CMD_NAME     = makeindex

# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact 
# LaTeX documents. This may be useful for small projects and may help to 
# save some trees in general.

COMPACT_LATEX          = NO

# The PAPER_TYPE tag can be used to set the paper type that is used 
# by the printer. Possible values are: a4, letter, legal and 
# executive. If left blank a4wide will be used.

PAPER_TYPE             = a4

# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX 
# packages that should be included in the LaTeX output.

EXTRA_PACKAGES         = 

# The LATEX_HEADER tag can be used to specify a personal LaTeX header for 
# the generated latex document. The header should contain everything until 
# the first chapter. If it is left blank doxygen will generate a 
# standard header. Notice: only use this tag if you know what you are doing!

LATEX_HEADER           = 

# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for 
# the generated latex document. The footer should contain everything after 
# the last chapter. If it is left blank doxygen will generate a 
# standard footer. Notice: only use this tag if you know what you are doing!

LATEX_FOOTER           = 

# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated 
# is prepared for conversion to pdf (using ps2pdf). The pdf file will 
# contain links (just like the HTML output) instead of page references 
# This makes the output suitable for online browsing using a pdf viewer.

PDF_HYPERLINKS         = YES

# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of 
# plain latex in the generated Makefile. Set this option to YES to get a 
# higher quality PDF documentation.

USE_PDFLATEX           = YES

# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. 
# command to the generated LaTeX files. This will instruct LaTeX to keep 
# running if errors occur, instead of asking the user for help. 
# This option is also used when generating formulas in HTML.

LATEX_BATCHMODE        = NO

# If LATEX_HIDE_INDICES is set to YES then doxygen will not 
# include the index chapters (such as File Index, Compound Index, etc.) 
# in the output.

LATEX_HIDE_INDICES     = NO

# If LATEX_SOURCE_CODE is set to YES then doxygen will include 
# source code with syntax highlighting in the LaTeX output. 
# Note that which sources are shown also depends on other settings 
# such as SOURCE_BROWSER.

LATEX_SOURCE_CODE      = NO

# The LATEX_BIB_STYLE tag can be used to specify the style to use for the 
# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See 
# http://en.wikipedia.org/wiki/BibTeX for more info.

LATEX_BIB_STYLE        = plain

#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------

# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output 
# The RTF output is optimized for Word 97 and may not look very pretty with 
# other RTF readers or editors.

GENERATE_RTF           = NO

# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank `rtf' will be used as the default path.

RTF_OUTPUT             = rtf

# If the COMPACT_RTF tag is set to YES Doxygen generates more compact 
# RTF documents. This may be useful for small projects and may help to 
# save some trees in general.

COMPACT_RTF            = NO

# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated 
# will contain hyperlink fields. The RTF file will 
# contain links (just like the HTML output) instead of page references. 
# This makes the output suitable for online browsing using WORD or other 
# programs which support those fields. 
# Note: wordpad (write) and others do not support links.

RTF_HYPERLINKS         = NO

# Load style sheet definitions from file. Syntax is similar to doxygen's 
# config file, i.e. a series of assignments. You only have to provide 
# replacements, missing definitions are set to their default value.

RTF_STYLESHEET_FILE    = 

# Set optional variables used in the generation of an rtf document. 
# Syntax is similar to doxygen's config file.

RTF_EXTENSIONS_FILE    = 

#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------

# If the GENERATE_MAN tag is set to YES (the default) Doxygen will 
# generate man pages

GENERATE_MAN           = NO

# The MAN_OUTPUT tag is used to specify where the man pages will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank `man' will be used as the default path.

MAN_OUTPUT             = man

# The MAN_EXTENSION tag determines the extension that is added to 
# the generated man pages (default is the subroutine's section .3)

MAN_EXTENSION          = .3

# If the MAN_LINKS tag is set to YES and Doxygen generates man output, 
# then it will generate one additional man file for each entity 
# documented in the real man page(s). These additional files 
# only source the real man page, but without them the man command 
# would be unable to find the correct page. The default is NO.

MAN_LINKS              = NO

#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------

# If the GENERATE_XML tag is set to YES Doxygen will 
# generate an XML file that captures the structure of 
# the code including all documentation.

GENERATE_XML           = NO

# The XML_OUTPUT tag is used to specify where the XML pages will be put. 
# If a relative path is entered the value of OUTPUT_DIRECTORY will be 
# put in front of it. If left blank `xml' will be used as the default path.

XML_OUTPUT             = xml

# The XML_SCHEMA tag can be used to specify an XML schema, 
# which can be used by a validating XML parser to check the 
# syntax of the XML files.

XML_SCHEMA             = 

# The XML_DTD tag can be used to specify an XML DTD, 
# which can be used by a validating XML parser to check the 
# syntax of the XML files.

XML_DTD                = 

# If the XML_PROGRAMLISTING tag is set to YES Doxygen will 
# dump the program listings (including syntax highlighting 
# and cross-referencing information) to the XML output. Note that 
# enabling this will significantly increase the size of the XML output.

XML_PROGRAMLISTING     = YES

#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------

# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will 
# generate an AutoGen Definitions (see autogen.sf.net) file 
# that captures the structure of the code including all 
# documentation. Note that this feature is still experimental 
# and incomplete at the moment.

GENERATE_AUTOGEN_DEF   = NO

#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------

# If the GENERATE_PERLMOD tag is set to YES Doxygen will 
# generate a Perl module file that captures the structure of 
# the code including all documentation. Note that this 
# feature is still experimental and incomplete at the 
# moment.

GENERATE_PERLMOD       = NO

# If the PERLMOD_LATEX tag is set to YES Doxygen will generate 
# the necessary Makefile rules, Perl scripts and LaTeX code to be able 
# to generate PDF and DVI output from the Perl module output.

PERLMOD_LATEX          = NO

# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be 
# nicely formatted so it can be parsed by a human reader.  This is useful 
# if you want to understand what is going on.  On the other hand, if this 
# tag is set to NO the size of the Perl module output will be much smaller 
# and Perl will parse it just the same.

PERLMOD_PRETTY         = YES

# The names of the make variables in the generated doxyrules.make file 
# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. 
# This is useful so different doxyrules.make files included by the same 
# Makefile don't overwrite each other's variables.

PERLMOD_MAKEVAR_PREFIX = 

#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------

# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will 
# evaluate all C-preprocessor directives found in the sources and include 
# files.

ENABLE_PREPROCESSING   = YES

# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro 
# names in the source code. If set to NO (the default) only conditional 
# compilation will be performed. Macro expansion can be done in a controlled 
# way by setting EXPAND_ONLY_PREDEF to YES.

MACRO_EXPANSION        = NO

# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
# then the macro expansion is limited to the macros specified with the 
# PREDEFINED and EXPAND_AS_DEFINED tags.

EXPAND_ONLY_PREDEF     = NO

# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
# pointed to by INCLUDE_PATH will be searched when a #include is found.

SEARCH_INCLUDES        = YES

# The INCLUDE_PATH tag can be used to specify one or more directories that 
# contain include files that are not input files but should be processed by 
# the preprocessor.

INCLUDE_PATH           = 

# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard 
# patterns (like *.h and *.hpp) to filter out the header-files in the 
# directories. If left blank, the patterns specified with FILE_PATTERNS will 
# be used.

INCLUDE_FILE_PATTERNS  = 

# The PREDEFINED tag can be used to specify one or more macro names that 
# are defined before the preprocessor is started (similar to the -D option of 
# gcc). The argument of the tag is a list of macros of the form: name 
# or name=definition (no spaces). If the definition and the = are 
# omitted =1 is assumed. To prevent a macro definition from being 
# undefined via #undef or recursively expanded use the := operator 
# instead of the = operator.

PREDEFINED             = @minxdoc_PREDEFINED@

# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
# this tag can be used to specify a list of macro names that should be expanded. 
# The macro definition that is found in the sources will be used. 
# Use the PREDEFINED tag if you want to use a different macro definition that 
# overrules the definition found in the source code.

EXPAND_AS_DEFINED      = 

# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then 
# doxygen's preprocessor will remove all references to function-like macros 
# that are alone on a line, have an all uppercase name, and do not end with a 
# semicolon, because these will confuse the parser if not removed.

SKIP_FUNCTION_MACROS   = YES

#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------

# The TAGFILES option can be used to specify one or more tagfiles. For each 
# tag file the location of the external documentation should be added. The 
# format of a tag file without this location is as follows: 
#   TAGFILES = file1 file2 ... 
# Adding location for the tag files is done as follows: 
#   TAGFILES = file1=loc1 "file2 = loc2" ... 
# where "loc1" and "loc2" can be relative or absolute paths 
# or URLs. Note that each tag file must have a unique name (where the name does 
# NOT include the path). If a tag file is not located in the directory in which 
# doxygen is run, you must also specify the path to the tagfile here.

TAGFILES               = 

# When a file name is specified after GENERATE_TAGFILE, doxygen will create 
# a tag file that is based on the input files it reads.

GENERATE_TAGFILE       = 

# If the ALLEXTERNALS tag is set to YES all external classes will be listed 
# in the class index. If set to NO only the inherited external classes 
# will be listed.

ALLEXTERNALS           = NO

# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed 
# in the modules index. If set to NO, only the current project's groups will 
# be listed.

EXTERNAL_GROUPS        = YES

# The PERL_PATH should be the absolute path and name of the perl script 
# interpreter (i.e. the result of `which perl').

PERL_PATH              = /usr/bin/perl

#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------

# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will 
# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base 
# or super classes. Setting the tag to NO turns the diagrams off. Note that 
# this option also works with HAVE_DOT disabled, but it is recommended to 
# install and use dot, since it yields more powerful graphs.

CLASS_DIAGRAMS         = NO

# You can define message sequence charts within doxygen comments using the \msc 
# command. Doxygen will then run the mscgen tool (see 
# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the 
# documentation. The MSCGEN_PATH tag allows you to specify the directory where 
# the mscgen tool resides. If left empty the tool is assumed to be found in the 
# default search path.

MSCGEN_PATH            = 

# If set to YES, the inheritance and collaboration graphs will hide 
# inheritance and usage relations if the target is undocumented 
# or is not a class.

HIDE_UNDOC_RELATIONS   = YES

# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is 
# available from the path. This tool is part of Graphviz, a graph visualization 
# toolkit from AT&T and Lucent Bell Labs. The other options in this section 
# have no effect if this option is set to NO (the default)

HAVE_DOT               = NO

# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is 
# allowed to run in parallel. When set to 0 (the default) doxygen will 
# base this on the number of processors available in the system. You can set it 
# explicitly to a value larger than 0 to get control over the balance 
# between CPU load and processing speed.

DOT_NUM_THREADS        = 0

# By default doxygen will use the Helvetica font for all dot files that 
# doxygen generates. When you want a differently looking font you can specify 
# the font name using DOT_FONTNAME. You need to make sure dot is able to find 
# the font, which can be done by putting it in a standard location or by setting 
# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the 
# directory containing the font.

DOT_FONTNAME           = Helvetica

# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. 
# The default size is 10pt.

DOT_FONTSIZE           = 10

# By default doxygen will tell dot to use the Helvetica font. 
# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to 
# set the path where dot can find it.

DOT_FONTPATH           = 

# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen 
# will generate a graph for each documented class showing the direct and 
# indirect inheritance relations. Setting this tag to YES will force the 
# CLASS_DIAGRAMS tag to NO.

CLASS_GRAPH            = NO

# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen 
# will generate a graph for each documented class showing the direct and 
# indirect implementation dependencies (inheritance, containment, and 
# class references variables) of the class with other documented classes.

COLLABORATION_GRAPH    = NO

# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen 
# will generate a graph for groups, showing the direct groups dependencies

GROUP_GRAPHS           = NO

# If the UML_LOOK tag is set to YES doxygen will generate inheritance and 
# collaboration diagrams in a style similar to the OMG's Unified Modeling 
# Language.

UML_LOOK               = NO

# If the UML_LOOK tag is enabled, the fields and methods are shown inside 
# the class node. If there are many fields or methods and many nodes the 
# graph may become too big to be useful. The UML_LIMIT_NUM_FIELDS 
# threshold limits the number of items for each type to make the size more 
# managable. Set this to 0 for no limit. Note that the threshold may be 
# exceeded by 50% before the limit is enforced.

UML_LIMIT_NUM_FIELDS   = 10

# If set to YES, the inheritance and collaboration graphs will show the 
# relations between templates and their instances.

TEMPLATE_RELATIONS     = NO

# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT 
# tags are set to YES then doxygen will generate a graph for each documented 
# file showing the direct and indirect include dependencies of the file with 
# other documented files.

INCLUDE_GRAPH          = NO

# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and 
# HAVE_DOT tags are set to YES then doxygen will generate a graph for each 
# documented header file showing the documented files that directly or 
# indirectly include this file.

INCLUDED_BY_GRAPH      = NO

# If the CALL_GRAPH and HAVE_DOT options are set to YES then 
# doxygen will generate a call dependency graph for every global function 
# or class method. Note that enabling this option will significantly increase 
# the time of a run. So in most cases it will be better to enable call graphs 
# for selected functions only using the \callgraph command.

CALL_GRAPH             = NO

# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then 
# doxygen will generate a caller dependency graph for every global function 
# or class method. Note that enabling this option will significantly increase 
# the time of a run. So in most cases it will be better to enable caller 
# graphs for selected functions only using the \callergraph command.

CALLER_GRAPH           = NO

# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
# will generate a graphical hierarchy of all classes instead of a textual one.

GRAPHICAL_HIERARCHY    = NO

# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES 
# then doxygen will show the dependencies a directory has on other directories 
# in a graphical way. The dependency relations are determined by the #include 
# relations between the files in the directories.

DIRECTORY_GRAPH        = NO

# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images 
# generated by dot. Possible values are svg, png, jpg, or gif. 
# If left blank png will be used. If you choose svg you need to set 
# HTML_FILE_EXTENSION to xhtml in order to make the SVG files 
# visible in IE 9+ (other browsers do not have this requirement).

DOT_IMAGE_FORMAT       = png

# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to 
# enable generation of interactive SVG images that allow zooming and panning. 
# Note that this requires a modern browser other than Internet Explorer. 
# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you 
# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files 
# visible. Older versions of IE do not have SVG support.

INTERACTIVE_SVG        = NO

# The tag DOT_PATH can be used to specify the path where the dot tool can be 
# found. If left blank, it is assumed the dot tool can be found in the path.

DOT_PATH               = 

# The DOTFILE_DIRS tag can be used to specify one or more directories that 
# contain dot files that are included in the documentation (see the 
# \dotfile command).

DOTFILE_DIRS           = 

# The MSCFILE_DIRS tag can be used to specify one or more directories that 
# contain msc files that are included in the documentation (see the 
# \mscfile command).

MSCFILE_DIRS           = 

# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of 
# nodes that will be shown in the graph. If the number of nodes in a graph 
# becomes larger than this value, doxygen will truncate the graph, which is 
# visualized by representing a node as a red box. Note that doxygen if the 
# number of direct children of the root node in a graph is already larger than 
# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note 
# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.

DOT_GRAPH_MAX_NODES    = 50

# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the 
# graphs generated by dot. A depth value of 3 means that only nodes reachable 
# from the root by following a path via at most 3 edges will be shown. Nodes 
# that lay further from the root node will be omitted. Note that setting this 
# option to 1 or 2 may greatly reduce the computation time needed for large 
# code bases. Also note that the size of a graph can be further restricted by 
# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.

MAX_DOT_GRAPH_DEPTH    = 0

# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent 
# background. This is disabled by default, because dot on Windows does not 
# seem to support this out of the box. Warning: Depending on the platform used, 
# enabling this option may lead to badly anti-aliased labels on the edges of 
# a graph (i.e. they become hard to read).

DOT_TRANSPARENT        = NO

# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output 
# files in one run (i.e. multiple -o and -T options on the command line). This 
# makes dot run faster, but since only newer versions of dot (>1.8.10) 
# support this, this feature is disabled by default.

DOT_MULTI_TARGETS      = NO

# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will 
# generate a legend page explaining the meaning of the various boxes and 
# arrows in the dot generated graphs.

GENERATE_LEGEND        = NO

# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will 
# remove the intermediate dot files that are used to generate 
# the various graphs.

DOT_CLEANUP            = YES

#!/usr/bin/env python

########################################################################
#                                                                      #
# This file is distributed with Minx but is not written by the Minx    #
# Project Developers. This file's original authors and their contact   #
# information are provided below in the __author__ and __website__     #
# variables. The Minx Project Developers would like to thank the       #
# authors of this program for making it available under the terms of   #
# the GPL, which allows us to bundle it with the Minx sources.         #
#                                                                      #
# NOTE: Recent versions of Debian (e.g., squeeze) and Ubuntu (e.g.,    #
# 12.04), make this program available in the python-doxypy package.    #
# However, it has not yet made its way into the FreeBSD ports          #
# collection (as of version 9). To simplify Minx development across    #
# these two platforms, we simply bundle doxypy with Minx. If and when  #
# doxypy becomes part of the package repositories of both these        #
# operating systems, we should no longer need to distribute doxypy     #
# along with Minx's source code.                                       #
#                                                                      #
# NOTE 2: This notice is the only change made to this file by the Minx #
# Project. Everything else is identical to the upstream version.       #
#                                                                      #
########################################################################

__applicationName__ = "doxypy"
__blurb__ = """
doxypy is an input filter for Doxygen. It preprocesses python
files so that docstrings of classes and functions are reformatted
into Doxygen-conform documentation blocks.
"""

__doc__ = __blurb__ + \
"""
In order to make Doxygen preprocess files through doxypy, simply
add the following lines to your Doxyfile:
	FILTER_SOURCE_FILES = YES
	INPUT_FILTER = "python /path/to/doxypy.py"
"""

__version__ = "0.4.2"
__date__ = "14th October 2009"
__website__ = "http://code.foosel.org/doxypy"

__author__ = (
	"Philippe 'demod' Neumann (doxypy at demod dot org)",
	"Gina 'foosel' Haeussge (gina at foosel dot net)" 
)

__licenseName__ = "GPL v2"
__license__ = """This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

import sys
import re

from optparse import OptionParser, OptionGroup

class FSM(object):
	"""Implements a finite state machine.
	
	Transitions are given as 4-tuples, consisting of an origin state, a target
	state, a condition for the transition (given as a reference to a function
	which gets called with a given piece of input) and a pointer to a function
	to be called upon the execution of the given transition. 
	"""
	
	"""
	@var transitions holds the transitions
	@var current_state holds the current state
	@var current_input holds the current input
	@var current_transition hold the currently active transition
	"""
	
	def __init__(self, start_state=None, transitions=[]):
		self.transitions = transitions
		self.current_state = start_state
		self.current_input = None
		self.current_transition = None
		
	def setStartState(self, state):
		self.current_state = state

	def addTransition(self, from_state, to_state, condition, callback):
		self.transitions.append([from_state, to_state, condition, callback])
		
	def makeTransition(self, input):
		"""Makes a transition based on the given input.
		
		@param	input	input to parse by the FSM
		"""
		for transition in self.transitions:
			[from_state, to_state, condition, callback] = transition
			if from_state == self.current_state:
				match = condition(input)
				if match:
					self.current_state = to_state
					self.current_input = input
					self.current_transition = transition
					if options.debug:
						print >>sys.stderr, "# FSM: executing (%s -> %s) for line '%s'" % (from_state, to_state, input)
					callback(match)
					return

class Doxypy(object):
	def __init__(self):
		string_prefixes = "[uU]?[rR]?"
		
		self.start_single_comment_re = re.compile("^\s*%s(''')" % string_prefixes)
		self.end_single_comment_re = re.compile("(''')\s*$")
		
		self.start_double_comment_re = re.compile("^\s*%s(\"\"\")" % string_prefixes)
		self.end_double_comment_re = re.compile("(\"\"\")\s*$")
		
		self.single_comment_re = re.compile("^\s*%s(''').*(''')\s*$" % string_prefixes)
		self.double_comment_re = re.compile("^\s*%s(\"\"\").*(\"\"\")\s*$" % string_prefixes)
		
		self.defclass_re = re.compile("^(\s*)(def .+:|class .+:)")
		self.empty_re = re.compile("^\s*$")
		self.hashline_re = re.compile("^\s*#.*$")
		self.importline_re = re.compile("^\s*(import |from .+ import)")

		self.multiline_defclass_start_re = re.compile("^(\s*)(def|class)(\s.*)?$")
		self.multiline_defclass_end_re = re.compile(":\s*$")
		
		## Transition list format
		#  ["FROM", "TO", condition, action]
		transitions = [
			### FILEHEAD
			
			# single line comments
			["FILEHEAD", "FILEHEAD", self.single_comment_re.search, self.appendCommentLine],
			["FILEHEAD", "FILEHEAD", self.double_comment_re.search, self.appendCommentLine],
			
			# multiline comments
			["FILEHEAD", "FILEHEAD_COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine],
			["FILEHEAD_COMMENT_SINGLE", "FILEHEAD", self.end_single_comment_re.search, self.appendCommentLine],
			["FILEHEAD_COMMENT_SINGLE", "FILEHEAD_COMMENT_SINGLE", self.catchall, self.appendCommentLine],
			["FILEHEAD", "FILEHEAD_COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine],
			["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD", self.end_double_comment_re.search, self.appendCommentLine],
			["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD_COMMENT_DOUBLE", self.catchall, self.appendCommentLine],
			
			# other lines
			["FILEHEAD", "FILEHEAD", self.empty_re.search, self.appendFileheadLine],
			["FILEHEAD", "FILEHEAD", self.hashline_re.search, self.appendFileheadLine],
			["FILEHEAD", "FILEHEAD", self.importline_re.search, self.appendFileheadLine],
			["FILEHEAD", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch],
			["FILEHEAD", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch],			
			["FILEHEAD", "DEFCLASS_BODY", self.catchall, self.appendFileheadLine],

			### DEFCLASS
			
			# single line comments
			["DEFCLASS", "DEFCLASS_BODY", self.single_comment_re.search, self.appendCommentLine],
			["DEFCLASS", "DEFCLASS_BODY", self.double_comment_re.search, self.appendCommentLine],
			
			# multiline comments
			["DEFCLASS", "COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine],
			["COMMENT_SINGLE", "DEFCLASS_BODY", self.end_single_comment_re.search, self.appendCommentLine],
			["COMMENT_SINGLE", "COMMENT_SINGLE", self.catchall, self.appendCommentLine],
			["DEFCLASS", "COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine],
			["COMMENT_DOUBLE", "DEFCLASS_BODY", self.end_double_comment_re.search, self.appendCommentLine],
			["COMMENT_DOUBLE", "COMMENT_DOUBLE", self.catchall, self.appendCommentLine],

			# other lines
			["DEFCLASS", "DEFCLASS", self.empty_re.search, self.appendDefclassLine],
			["DEFCLASS", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch],
			["DEFCLASS", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch],
			["DEFCLASS", "DEFCLASS_BODY", self.catchall, self.stopCommentSearch],
			
			### DEFCLASS_BODY
			
			["DEFCLASS_BODY", "DEFCLASS", self.defclass_re.search, self.startCommentSearch],
			["DEFCLASS_BODY", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.startCommentSearch],
			["DEFCLASS_BODY", "DEFCLASS_BODY", self.catchall, self.appendNormalLine],

			### DEFCLASS_MULTI
			["DEFCLASS_MULTI", "DEFCLASS", self.multiline_defclass_end_re.search, self.appendDefclassLine],
			["DEFCLASS_MULTI", "DEFCLASS_MULTI", self.catchall, self.appendDefclassLine],
		]
		
		self.fsm = FSM("FILEHEAD", transitions)
		self.outstream = sys.stdout
		
		self.output = []
		self.comment = []
		self.filehead = []
		self.defclass = []
		self.indent = ""

	def __closeComment(self):
		"""Appends any open comment block and triggering block to the output."""
		
		if options.autobrief:
			if len(self.comment) == 1 \
			or (len(self.comment) > 2 and self.comment[1].strip() == ''):
				self.comment[0] = self.__docstringSummaryToBrief(self.comment[0])
			
		if self.comment:
			block = self.makeCommentBlock()
			self.output.extend(block)
			
		if self.defclass:
			self.output.extend(self.defclass)

	def __docstringSummaryToBrief(self, line):
		"""Adds \\brief to the docstrings summary line.
		
		A \\brief is prepended, provided no other doxygen command is at the
		start of the line.
		"""
		stripped = line.strip()
		if stripped and not stripped[0] in ('@', '\\'):
			return "\\brief " + line
		else:
			return line
	
	def __flushBuffer(self):
		"""Flushes the current outputbuffer to the outstream."""
		if self.output:
			try:
				if options.debug:
					print >>sys.stderr, "# OUTPUT: ", self.output
				print >>self.outstream, "\n".join(self.output)
				self.outstream.flush()
			except IOError:
				# Fix for FS#33. Catches "broken pipe" when doxygen closes 
				# stdout prematurely upon usage of INPUT_FILTER, INLINE_SOURCES 
				# and FILTER_SOURCE_FILES.
				pass
		self.output = []

	def catchall(self, input):
		"""The catchall-condition, always returns true."""
		return True
	
	def resetCommentSearch(self, match):
		"""Restarts a new comment search for a different triggering line.
		
		Closes the current commentblock and starts a new comment search.
		"""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: resetCommentSearch" 
		self.__closeComment()
		self.startCommentSearch(match)
	
	def startCommentSearch(self, match):
		"""Starts a new comment search.
		
		Saves the triggering line, resets the current comment and saves
		the current indentation.
		"""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: startCommentSearch"
		self.defclass = [self.fsm.current_input]
		self.comment = []
		self.indent = match.group(1)
	
	def stopCommentSearch(self, match):
		"""Stops a comment search.
		
		Closes the current commentblock, resets	the triggering line and
		appends the current line to the output.
		"""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: stopCommentSearch" 
		self.__closeComment()
		
		self.defclass = []
		self.output.append(self.fsm.current_input)
	
	def appendFileheadLine(self, match):
		"""Appends a line in the FILEHEAD state.
		
		Closes the open comment	block, resets it and appends the current line.
		""" 
		if options.debug:
			print >>sys.stderr, "# CALLBACK: appendFileheadLine" 
		self.__closeComment()
		self.comment = []
		self.output.append(self.fsm.current_input)

	def appendCommentLine(self, match):
		"""Appends a comment line.
		
		The comment delimiter is removed from multiline start and ends as
		well as singleline comments.
		"""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: appendCommentLine" 
		(from_state, to_state, condition, callback) = self.fsm.current_transition
		
		# single line comment
		if (from_state == "DEFCLASS" and to_state == "DEFCLASS_BODY") \
		or (from_state == "FILEHEAD" and to_state == "FILEHEAD"):
			# remove comment delimiter from begin and end of the line
			activeCommentDelim = match.group(1)
			line = self.fsm.current_input
			self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):line.rfind(activeCommentDelim)])

			if (to_state == "DEFCLASS_BODY"):
				self.__closeComment()
				self.defclass = []
		# multiline start
		elif from_state == "DEFCLASS" or from_state == "FILEHEAD":
			# remove comment delimiter from begin of the line
			activeCommentDelim = match.group(1)
			line = self.fsm.current_input
			self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):])
		# multiline end
		elif to_state == "DEFCLASS_BODY" or to_state == "FILEHEAD":
			# remove comment delimiter from end of the line
			activeCommentDelim = match.group(1)
			line = self.fsm.current_input
			self.comment.append(line[0:line.rfind(activeCommentDelim)])
			if (to_state == "DEFCLASS_BODY"):
				self.__closeComment()
				self.defclass = []
		# in multiline comment
		else:
			# just append the comment line
			self.comment.append(self.fsm.current_input)
	
	def appendNormalLine(self, match):
		"""Appends a line to the output."""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: appendNormalLine" 
		self.output.append(self.fsm.current_input)
		
	def appendDefclassLine(self, match):
		"""Appends a line to the triggering block."""
		if options.debug:
			print >>sys.stderr, "# CALLBACK: appendDefclassLine" 
		self.defclass.append(self.fsm.current_input)
	
	def makeCommentBlock(self):
		"""Indents the current comment block with respect to the current
		indentation level.

		@returns a list of indented comment lines
		"""
		doxyStart = "##"
		commentLines = self.comment
		
		commentLines = map(lambda x: "%s# %s" % (self.indent, x), commentLines)
		l = [self.indent + doxyStart]
		l.extend(commentLines)
			 
		return l
	
	def parse(self, input):
		"""Parses a python file given as input string and returns the doxygen-
		compatible representation.
		
		@param	input	the python code to parse
		@returns the modified python code
		""" 
		lines = input.split("\n")
		
		for line in lines:
			self.fsm.makeTransition(line)
			
		if self.fsm.current_state == "DEFCLASS":
			self.__closeComment()
		
		return "\n".join(self.output)
	
	def parseFile(self, filename):
		"""Parses a python file given as input string and returns the doxygen-
		compatible representation.
		
		@param	input	the python code to parse
		@returns the modified python code
		""" 
		f = open(filename, 'r')
		
		for line in f:
			self.parseLine(line.rstrip('\r\n'))
		if self.fsm.current_state == "DEFCLASS":
			self.__closeComment()
			self.__flushBuffer()
		f.close()
	
	def parseLine(self, line):
		"""Parse one line of python and flush the resulting output to the 
		outstream.
		
		@param	line	the python code line to parse
		"""
		self.fsm.makeTransition(line)
		self.__flushBuffer()
	
def optParse():
	"""Parses commandline options."""
	parser = OptionParser(prog=__applicationName__, version="%prog " + __version__)
	
	parser.set_usage("%prog [options] filename")
	parser.add_option("--autobrief",
		action="store_true", dest="autobrief",
		help="use the docstring summary line as \\brief description"
	)
	parser.add_option("--debug",
		action="store_true", dest="debug",
		help="enable debug output on stderr"
	)
	
	## parse options
	global options
	(options, filename) = parser.parse_args()
	
	if not filename:
		print >>sys.stderr, "No filename given."
		sys.exit(-1)
	
	return filename[0]

def main():
	"""Starts the parser on the file given by the filename as the first 
	argument on the commandline.
	"""
	filename = optParse()
	fsm = Doxypy()
	fsm.parseFile(filename)

if __name__ == "__main__":
	main()

</body>
</html>

<!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">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link href="$relpath$tabs.css" rel="stylesheet" type="text/css"/>
<link href="$relpath$dox.css" rel="stylesheet" type="text/css" />
$treeview
$search
$mathjax
</head>
<body>
<div id="top"><!-- do not remove this div! -->

<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <!--BEGIN PROJECT_LOGO-->
  <td id="projectlogo"><img alt="Logo" src="$relpath$$projectlogo"/></td>
  <!--END PROJECT_LOGO-->
  <!--BEGIN PROJECT_NAME-->
  <td style="padding-left: 0.5em;">
   <div id="projectname">
     <a href="../wiki/home.wiki">$projectname</a>
     <!--BEGIN PROJECT_NUMBER-->
     &#160;<span id="projectnumber">$projectnumber</span>
     <!--END PROJECT_NUMBER-->
   </div>
   <!--BEGIN PROJECT_BRIEF-->
   <div id="projectbrief">
     <a href="index.html">$projectbrief</a>
   </div>
   <!--END PROJECT_BRIEF-->
  </td>
  <!--END PROJECT_NAME-->
  <!--BEGIN !PROJECT_NAME-->
   <!--BEGIN PROJECT_BRIEF-->
    <td style="padding-left: 0.5em;">
    <div id="projectbrief">$projectbrief</div>
    </td>
   <!--END PROJECT_BRIEF-->
  <!--END !PROJECT_NAME-->
  <!--BEGIN DISABLE_INDEX-->
   <!--BEGIN SEARCHENGINE-->
   <td>$searchbox</td>
   <!--END SEARCHENGINE-->
  <!--END DISABLE_INDEX-->
 </tr>
 </tbody>
</table>
</div>
<!--END TITLEAREA-->

/**
    @file  mainpage.hh
    @brief Contents of main page of API docs.

    This file exists only to be able to put stuff on the
    Doxygen-generated docs' main page. It is not actually used by
    minxlib or any other part of Minx.
*/

/*
    Copyright (C) 2012 The Minx Project Developers

    See wiki/copyright.wiki for the full list of authors who have
    contributed to this project.
*/

/*
    This file is part of Minx.

    Minx is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Minx is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
    License for more details.

    You should have received a copy of the GNU General Public License
    along with Minx. If not, see <http://www.gnu.org/licenses/>.
*/

//----------------------- API DOCS MAIN PAGE ---------------------------

/**
    @mainpage Minx API Documentation

    Minx is not really a tiling window manager. Rather it is a library
    that allows you to write your own tiling window manager. However, in
    case you don't want to write your own window manager, it provides a
    default configuration so that it can be used with minimal effort.
    Minx also tries to make it easy to change the defaults to suit your
    tastes.

    However, since it is impossible to anticipate everyone's
    preferences, Minx provides the necessary infrastructure to radically
    alter its behaviour. These pages document the various classes and
    functions that Minx implements to enable end-users to write a highly
    customized window manager.

    <hr>

    @section sec_core Minx Core

    Here are the different classes in Minx's Python core:

        @li @ref minx.core.wm.wm "wm"
        @li @ref minx.core.config.config "config"
        @li @ref grp_minx_core_hooks "hooks"
        @li @ref grp_minx_core_layman "layman"
        @li @ref grp_minx_version "version"
        @li @ref grp_minx_core_window "window"
        @li @ref minx.core.focus_list.focus_list "focus_list"
        @li @ref minx.core.xevents.xevents "xevents"

    Not all of the above classes are meant to be used directly by
    end-users. At this time, in fact, only the @ref minx.core.wm.wm "wm",
    @ref minx.core.config.config "config", and
    @ref grp_minx_core_hooks "hooks" classes are for public
    consumption. The @ref grp_minx_version "minx.version" object may
    also be used. Everything else should be considered internal to Minx.

    <hr>

    @section sec_layouts Minx Layouts

    Minx comes with the following layout classes:

        @li @ref minx.layout.base.base "base"
        @li @ref minx.layout.full.full "full"

    You can implement your own layouts by deriving from the
    @ref minx.layout.base.base "minx.layout.base" class and overriding
    some of its methods.

    <hr>

    @section sec_minxlib minxlib

    As you can tell from the above, Minx is written in Python and is
    largely concerned with the details of laying out windows,
    circulating input focus, and so on. However, in order to be able to
    actually achieve that functionality, it needs to talk to the
    underlying display server, which it does using minxlib, a custom
    Xlib wrapper written in C++.

    minxlib provides the Python parts of Minx a high-level,
    object-oriented API for talking to the X server. In general,
    end-users will rely on Minx's Python classes to effect various
    customizations and should not need to use minxlib directly.
    Nonetheless, the following pages document its public interface:

        @li @ref minxlib::display "display"
        @li @ref minxlib::window "window"
        @li @ref grp_minxlib_events "Event Classes"
        @li @ref grp_minxlib_exceptions "Exception Classes"
        @li @ref grp_minxlib_keymap "Key Bindings API"
        @li @ref minxlib::logging "logging"
        @li @ref minxlib::version "version"
*/

//----------------------------------------------------------------------

/**********************************************/
/* Editor config:                             */
/**********************************************/
/* Local Variables:                           */
/* indent-tabs-mode: nil                      */
/* c-basic-offset: 4                          */
/* End:                                       */
/**********************************************/
/* vim: set expandtab shiftwidth=4 tabstop=4: */
/**********************************************/

#
# __init__.py -- initialization for minx.layout module
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#------------------------------- IMPORTS --------------------------------

# Pull in various classes from minx.layout so that end-users see them,
# for example, as minx.layout.full instead of minx.layout.full.full, and
# so on.
from base import base
from full import full

#------------------------------- EXPORTS --------------------------------

__all__ = ["base", "full"]

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# base.py -- base class for Minx layouts
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#-------------------------- MODULE DOC STRING ---------------------------

"""@package minx.layout.base
Base class for Minx layouts.

This module implements a base class for layouts.

"""

#------------------------------- IMPORTS --------------------------------

# Standard library
import logging

# Minx
import minx.core.layman
from minx.core import minxlib

#---------------------------- MODULE LOGGER -----------------------------

logger = logging.getLogger(__name__)

#--------------------------- EVENT HANDLERS -----------------------------

# Since layouts use X windows to manage their windows, the layout window
# itself will be visible when a layout has no windows to manage. We don't
# want that; we want layouts to be invisible. To effect that
# invisibility, we map the layout's window when a window is added to the
# layout and unmap it when it no longer has any visible windows.
#
# The following event handlers take care of the above-mentioned strategy
# for keeping layouts invisible.
#
# NOTE: Rather than rely on the event dispatching implemented in xevents,
# we add our own hooks for the relevant X events because we don't want
# layout subclasses to be able to override this mechanism nor require
# them to have to call base class methods in order to ensure correct
# operation of things such as layout invisibility.

# Need the layout manager maintained by the main window manager object so
# that we can find the layouts for different windows.
_layouts = None

# When a window is reparented, show its layout if the layout isn't
# already visible and then let the layout object know so it can readjust
# window geometries as required.
def _on_reparent(e):
    try:
        logger.debug('window {} reparented by {}'.
                     format(e.target.id, e.new_parent.id))

        layout = _layouts.find(e.new_parent)
        logger.debug('window {} being managed by layout {}'.
                     format(e.target.id, layout))

        if not layout.window.is_mapped():
           logger.debug('showing layout {}'.format(layout))
           layout.window.show()

        layout.reparented(e.target)

    except minx.core.layman.unknown_layout:
        logger.warning('no layout corresponding to window {}'.
                       format(e.new_parent))
        logger.debug('window {} not being managed (bogus reparent_notify?)'.
                     format(e.target.id))

# When a window is unmapped, also unmap its layout if the layout has no
# more visible windows.
def _on_unmap(e):
    try:
        logger.debug('window {} unmapped'.format(e.target.id))

        layout = _layouts.find(e.parent)
        logger.debug('window {} being managed by layout {}'.
                     format(e.target.id, layout))

        for w in layout.window.children():
            if w.is_mapped():
               logger.debug('layout {} has visible child {}; no need to hide'.
                            format(layout, w.id))
               return

        logger.debug('hiding layout {} because it has no visible children'.
                     format(layout))
        layout.window.hide()

    except minx.core.layman.unknown_layout:
        pass

# Whenever focus changes, inform the layouts managing the affected
# windows (in case they need to readjust window geometries to take
# un/focused border sizes into account).
def _on_focus_in(e):
    try:
        _layouts.find(e.target.parent()).focused(e.target)
    except minx.core.layman.unknown_layout:
        pass

def _on_focus_out(e):
    try:
        _layouts.find(e.target.parent()).unfocused(e.target)
    except minx.core.layman.unknown_layout:
        pass

#-------------------------------- CLASS ---------------------------------

class base:
    """A base class for Minx layouts.

    This class implements a base class from which all Minx layout classes
    must be derived. This class is not meant to be instantiated; instead,
    you should instantiate one of the layout subclasses provided by Minx
    (or one of the custom layouts you implement yourself).

    """

    # Constructor
    def __init__(self, m, p, r = None):
        """Layout base class constructor.

        @param m The @ref minx.core.wm.wm "main window manager object".
        @param p The layout's parent @ref minxlib::window "minxlib.window".
        @param r The rectangle within parent window assigned to this layout.

        Each layout class's constructor must call this base class
        constructor, passing it at least the parameters m and p, which we
        need because a layout is basically an X window encapsulated by a
        Python object with some additional methods tacked on. Thus, in
        order to be able to create the layout window, we need the display
        connection (which is in the @ref minx.core.wm.wm "wm" class) and
        the parent window of the layout window.

        The parameter r is optional. It specifies the rectangle within
        the parent window that the layout will occupy. It should be a
        tuple of four integers. The first two integers in this tuple
        specify the x and y coordinates respectively of the layout
        window's top-left corner; the third and fourth integers are the
        layout window's width and height respectively.

        If r is not supplied by the subclass constructor, the layout will
        occupy the entire area of the parent window.

        After creating the layout's window, this method sets some
        properties on the newly created window and then maps it on screen.

        @note As mentioned earlier, this class is not meant to be
        instantiated directly. Thus, this constructor must only be called
        by subclasses.

        """
        global _layouts
        if _layouts == None:
           _layouts = m.layouts
           m.hooks.add('x_reparent_notify', _on_reparent, m.hooks.MAX_PRIORITY)
           m.hooks.add(   'x_unmap_notify', _on_unmap,    m.hooks.MAX_PRIORITY)
           m.hooks.add('x_focus_in',  _on_focus_in )
           m.hooks.add('x_focus_out', _on_focus_out)

        x, y, w, h = p.geometry()[:4] # don't need border width
        if r != None: # use supplied rectangle instead of entire parent window
           x, y, w, h = r

        self.window = m.display.create_window(p, x, y, w, h)

        name = 'minx.layout.{}.{}'.format(self.__class__.__name__,
                                          self.window.id)
        self.window.set_properties({'class': 'minx.layout', 'name' : name})
        self.window.select_events(minxlib.substructure_redirect_mask |
                                  minxlib.substructure_notify_mask)

    # Convert layout to string
    def __str__(self):
        """Return layout's name.

        This method will convert the layout object to a human-readable
        string representation (which is useful for debugging as well as
        identifying layouts).

        """
        prop = self.window.properties()
        return prop['name']

    # Check if layout will manage window
    def will_manage(self, w):
        """Check if this layout is willing to manage specified window.

        @param w The @ref minxlib::window "minxlib.window" to be managed.

        This method returns True if the layout is willing to manage the
        window w, False otherwise.

        The intent of this function is to allow layouts to decide whether
        or not they want to accept a window. For example, if a layout is
        written to expressly work with a particular application, it can
        return True for that application's windows and False for all the
        others.

        This method may be overridden by layout subclasses. The base
        class implementation returns True. Thus, unless a subclass
        overrides this function, it will be taken as willing to manage
        all windows.

        """
        logger.debug('layout {} will manage window {}'.format(self, w.id))
        return True

    # Manage specified window
    def add(self, w):
        """Add a window to be managed by this layout.

        @param w The @ref minxlib::window "minxlib.window" to be managed.

        This method tells the layout that it should manage the given
        window, which involves, among other things, reparenting the
        client window so that this layout becomes its parent.

        """
        w.select_events(minxlib.focus_change_mask)
        w.reparent(self.window)

    # Reparent notification
    def reparented(self, w):
        """Reparent notification.

        @param w The @ref minxlib::window "minxlib.window" that was reparented.

        When the @ref minx.core.wm.wm "main window manager object"
        receives a <tt>reparent_notify</tt> message in its event loop, it
        will eventually end up calling this method on the layout object
        that has reparented the window w.

        This method is meant to be overridden by layout subclasses. The
        base class implementation does nothing.

        """
        logger.warning('unhandled reparent_notify by layout ({})'.
                       format(self))

    # Configure requests
    def configure_request(self, n, x, y, w, h):
        """Decide window geometry on configure requests for top-level windows.

        @param  n The @ref minxlib::window "minxlib.window" to be configured.
        @param  x x-coordinate of window's top-left corner.
        @param  y y-coordinate of window's top-left corner.
        @param  w Window width.
        @param  h Window height.
        @return Tuple containing new geometry.

        When the @ref minx.core.wm.wm "main window manager object"
        receives a <tt>configure_request</tt> message in its event loop,
        it will eventually end up calling this method on the layout
        object that has reparented the window n. This method is meant to
        be overridden by layout subclasses; the base class implementation
        does nothing.

        Subclasses should return a 4-tuple of integers containing the new
        window geometry to apply in accordance with their particular
        layout policies. The first two numbers in this tuple specify the
        x and y coordinates of the window's top-left corner; the third
        and fourth numbers are the window's width and height
        respectively.

        The @ref minx.core.wm.wm "wm" object's <tt>configure_request</tt>
        event handler will use the returned tuple to honour the window's
        configure request. To clarify, layouts should not directly add a
        hook for <tt>x_configure_request</tt>; instead, they should let
        the main window manager object do that and override this method
        to let the main <tt>wm</tt> object know how to configure the
        windows they are managing.

        """
        logger.warning('unhandled configure_request by layout ({})'.
                       format(self))
        return (x, y, w, h)

    # Map requests
    def map_request(self, w):
        """Resize top-level window before it gets mapped to screen.

        @param w The @ref minxlib::window "minxlib.window" to be mapped.

        When the @ref minx.core.wm.wm "main window manager object"
        receives a <tt>map_request</tt> message in its event loop, it
        will eventually end up calling this method on the layout object
        that has reparented the window w. This method is meant to be
        overridden by layout subclasses; the base class implementation
        does nothing.

        The intent of this method is to give layouts an opportunity to
        move and resize the windows they are managing just before a
        window gets mapped. Layouts should not themselves map the window
        (though no harm should come from that). Rather, they should let
        the @ref minx.core.wm.wm "main window manager object" map windows
        and, in this method, if necessary, restrict themselves to
        reconfiguring their windows to match their layout policy.

        """
        logger.warning('unhandled map_request by layout ({})'.
                       format(self))

    # Focus change events
    def focused(self, w):
        """Focus-in notification.

        @param w The focused @ref minxlib::window "minxlib.window".

        When the @ref minx.core.wm.wm "main window manager object"
        receives a <tt>focus_in</tt> message in its event loop, it will
        eventually end up calling this method on the layout object that
        has reparented the window w. This method is meant to be
        overridden by layout subclasses; the base class implementation
        does nothing.

        The intent of this method is to inform layouts about changes in
        the input focus. When a window receives the input focus, the
        window manager may change its border color and size. And when
        that happens, the layout managing the newly focused window may
        well have to adjust the geometries of one/more/all of the windows
        it is managing to take into account the new border size.

        """
        logger.warning('unhandled focus_in for window {} by layout {}'.
                       format(w.id, self))

    def unfocused(self, w):
        """Focus-out notification.

        @param w The @ref minxlib::window "minxlib.window" that lost focus.

        When the @ref minx.core.wm.wm "main window manager object"
        receives a <tt>focus_out</tt> message in its event loop, it will
        eventually end up calling this method on the layout object that
        has reparented the window w. This method is meant to be
        overridden by layout subclasses; the base class implementation
        does nothing.

        The intent of this method is to inform layouts about changes in
        the input focus. When a window loses the input focus, the window
        manager may change its border color and size. Of course, when
        that happens, the layout managing the newly unfocused window may
        well have to adjust the geometries of one/more/all of the windows
        it is managing to take into account the new border size.

        """
        logger.warning('unhandled focus_out for window {} by layout {}'.
                       format(w.id, self))

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# full.py -- layout that occupies the entire area of its parent window
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

#-------------------------- MODULE DOC STRING ---------------------------

"""@package minx.layout.full
Layout that occupies the entire area of its parent window.

This module implements a layout that resizes all the windows it manages
so that they occupy the entire area of the layout's parent window.

"""

#------------------------------- IMPORTS --------------------------------

# Standard library
import logging

# Minx
from base import base

#-------------------------- MODULE LOGGER ------------------------------

logger = logging.getLogger(__name__)

#-------------------------------- CLASS ---------------------------------

class full(base):
    """Layout to occupy full area of parent window.

    This layout resizes all the windows it manages so that they occupy
    the entire area of the layout's parent window. Obviously, this
    strategy means that only one application window will be visible at a
    time.

    """

    # Create layout object
    def __init__(self, m, p, r = None):
        """Create a full layout object.

        @param m The @ref minx.core.wm.wm "main window manager object."
        @param p The layout's parent @ref minxlib::window "minxlib.window".
        @param r The rectangle within parent window assigned to this layout.

        When you create a full layout object, you should supply the main
        window manager object so that the layout can access the X server
        connection, any config settings it needs, etc. Additionally, the
        layout needs to know its parent window.

        The optional parameter r specifies the rectangle within the
        parent window that the layout will occupy. If it is not supplied,
        the layout will occupy the entire area of the parent window. If
        it is given, it should be a tuple containing four integers, the
        first two of which are the x and y coordinates of the layout's
        target area's top-left corner and the remaining two are the
        rectangle's width and height.

        Since Minx layouts are X windows, this constructor will create a
        child window of the specified parent, set appropriate properties
        to mark it as a layout, set the event mask, etc.

        """
        base.__init__(self, m, p, r)

    # Reparent notification
    def reparented(self, w):
        """Reparent notification.

        @param w The @ref minxlib::window "minxlib.window" that was reparented.

        When this layout manages a window, in the resulting reparent
        notification, we ensure that the size of the managed window w
        matches the size of the layout itself.

        """
        logger.info('window {} reparented by full layout ({})'.
                    format(w.id, self.window.id))
        self._resize(w)

    # Configure request
    def configure_request(self, n, x, y, w, h):
        """Configure request handler.

        @param  n The @ref minxlib::window "minxlib.window" to be configured.
        @param  x x-coordinate of window's top-left corner.
        @param  y y-coordinate of window's top-left corner.
        @param  w Window width.
        @param  h Window height.
        @return Tuple containing new geometry.

        This layout resizes the windows it manages to always occupy the
        entire area available to the layout. Thus, in response to a
        configure request for one of its windows, it will return the
        layout's geometry (adjusted to take into account the target
        window's border width).

        """
        logger.debug('full layout {} configuring top-level window {}'.
                     format(self.window.id, n.id))

        b = n.geometry()[4] # window's border width
        d = self.window.geometry()[:4]
        logger.debug('window {} border width = {}, '.format(n.id, b) +
                     'layout geometry = {}x{}+{}+{}'.format(d[2], d[3],
                                                            d[0], d[1]))
        d[2] -= 2*b # reduce window width  to ensure borders are visible
        d[3] -= 2*b # reduce window height to ensure borders are visible
        return (0, 0, d[2], d[3])

    # Map request
    def map_request(self, w):
        """Resize top-level window before it gets mapped to screen.

        @param w The @ref minxlib::window "minxlib.window" to be mapped.

        Before the full layout maps a window, it will compare the
        window's geometry against its own. If the two don't match, it
        will resize the window to make it fill the layout's entire area.

        """
        logger.debug('full layout {} resizing window {} before mapping'.
                     format(self.window.id, w.id))
        self._resize(w)

    # Focus change events
    def focused(self, w):
        """Focus-in notification.

        @param w The focused @ref minxlib::window "minxlib.window".

        When a window receives the input focus, resize it to account for
        potentially new border size.

        """
        logger.debug('full layout {} resizing focused window {}'.
                     format(self.window.id, w.id))
        self._resize(w)

    def unfocused(self, w):
        """Focus-out notification.

        @param w The unfocused @ref minxlib::window "minxlib.window".

        When a window loses the input focus, resize it to account for
        potentially new border size.

        """
        logger.debug('full layout {} resizing unfocused window {}'.
                     format(self.window.id, w.id))
        self._resize(w)

    # Resize window to fill layout
    def _resize(self, w):
        """Resize top-level window to fill entire layout area.

        @param w The @ref minxlib::window "minxlib.window" to be mapped.

        This is a helper method that compares the window w's geometry
        against the full layout's geometry and, if the two don't match,
        resizes w to make it fill the layout's entire area (taking into
        account the border width of w).

        @note This is a private method meant to be used only by the full
        layout class itself and should not be called directly by clients.

        """
        b = w.geometry() # window geometry with border width
        g = b[:4]        # window geometry w/o  border width
        d = self.window.geometry()
        logger.debug('window geometry: {}x{}+{}+{} [{}], '.
                     format(b[2], b[3], b[0], b[1], b[4]) +
                     'full layout {} geometry: {}x{}+{}+{}'.
                     format(self.window.id, d[2], d[3], d[0], d[1]))

        d[2] -= 2*b[4] # reduce window width  to ensure borders are visible
        d[3] -= 2*b[4] # reduce window height to ensure borders are visible
        if g[2:] == d[2:4]: # window and layout have the same size
           pass
        else: # need to adjust window size to match layout
           logger.info('full layout {} resetting window {} '.
                       format(self.window.id, w.id) +
                       'geometry to {}x{}+0+0'.format(d[2], d[3]))
           w.move_resize(0, 0, d[2], d[3])

#-----------------------------------------------------------------------

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# py-indent-offset: 4                        #
# python-indent: 4                           #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

#
# minxlib build spec
#

#
# Copyright (C) 2012 The Minx Project Developers
#
# See wiki/copyright.wiki in the top-level directory of the Minx source
# distribution for the full list of authors who have contributed to this
# project.
#

#
# This file is part of Minx.
#
# Minx is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your
# option) any later version.
#
# Minx is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with Minx. If not, see <http://www.gnu.org/licenses/>.
#

# Min cmake version
cmake_minimum_required(VERSION 2.8)

# Project name
project(minxlib)

# Library checks
find_package(X11 REQUIRED)
find_package(PythonLibs REQUIRED)
find_package(Boost COMPONENTS python REQUIRED)

# Compiler flags
add_definitions(-Wall -Wextra)
include_directories(${X11_INCLUDE_DIR}
                    ${Boost_INCLUDE_DIRS}
                    ${PYTHON_INCLUDE_DIRS})

# Check if we have Xinerama
if(X11_Xinerama_FOUND)
    set(X11_LIBRARIES ${X11_LIBRARIES} ${X11_Xinerama_LIB})
    add_definitions(-DMINXLIB_HAS_XINERAMA)
    set(minxlib_DOXYGEN_DEFINES MINXLIB_HAS_XINERAMA)
endif()

# Libraries we need to link against
set(minxlib_LIBS ${minxlib_LIBS}
    ${X11_LIBRARIES} ${Boost_LIBRARIES} ${PYTHON_LIBRARIES})

# Sources
set(minxlib_SOURCES python.cc type_info.cc util.cc logging.cc keymap.cc
                    exception.cc event.cc display.cc
                    window.cc root_window.cc)

# Add version.cc to source list if we're on the release branch (version
# numbering API does not exist on development branches).
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/version.cc")
    set(minxlib_SOURCES ${minxlib_SOURCES} version.cc)
    add_definitions(-DMINXLIB_HAS_VERSION_API)
endif()

# Final output from sources
add_library(minxlib SHARED ${minxlib_SOURCES})
target_link_libraries(minxlib ${minxlib_LIBS})

# Since minxlib is meant to be a Python module usable by the Minx core,
# we have to adjust some of its output parameters. Firstly, we have to
# send it to the minx.core directory. And, we have to elide the lib
# prefix from the name of the .so file to allow Python modules to import
# it as "minxlib" rather than "libminxlib".
set_target_properties(minxlib PROPERTIES
                      LIBRARY_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR}/core)
set_target_properties(minxlib PROPERTIES PREFIX "") # don't want "lib" prefix

##############################################
# Editor config:                             #
##############################################
# Local Variables:                           #
# indent-tabs-mode: nil                      #
# sh-basic-offset: 4                         #
# End:                                       #
##############################################
# vim: set expandtab shiftwidth=4 tabstop=4: #
##############################################

/*
    @file  display.cc
    @brief Implementation of API defined in display.hh.
*/

/*
    Copyright (C) 2012 The Minx Project Developers

    See wiki/copyright.wiki in the top-level directory of the Minx
    source distribution for the full list of authors who have
    contributed to this project.
*/

/*
    This file is part of Minx.

    Minx is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Minx is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
    License for more details.

    You should have received a copy of the GNU General Public License
    along with Minx. If not, see <http://www.gnu.org/licenses/>.
*/

//----------------------------- HEADERS --------------------------------

// minxlib
#include "display.hh"
#include "root_window.hh"
#include "window.hh"
#include "event.hh"
#include "logging.hh"
#include "python.hh"

// Xlib
#ifdef MINXLIB_HAS_XINERAMA
#include <X11/extensions/Xinerama.h>
#endif

// Standard C++
#include <set>

//------------------ INITIALIZATION AND CLEAN-UP -----------------------

namespace minxlib {

// Interface object for taking advantage of Python's standard logging
// module's facilities.
static logging logger ;

// For keeping track of which minxlib display object corresponds to
// which Xlib Display object (because Xlib error handlers don't pass
// back any client data).
std::map<Display*, display*> display::m_display_map ;

// Constructor: connect to X server and setup error handlers
display::display(const std::string& name, bool sync)
    : m_display(XOpenDisplay(const_cast<char*>(name.c_str()))),
      m_fatal(true) // wait to check above connection before declaring okay
{
    if (!m_display) {
        std::string server(XDisplayName(const_cast<char*>(name.c_str()))) ;
        logger.critical() << "unable to connect to X server " << server ;
        connection_error::raise(server) ;
    }

    m_fatal = false ;
    m_display_map[m_display] = this ;
    logger.debug() << "registered display object "
                   << reinterpret_cast<unsigned long>(m_display) << " -> "
                   << reinterpret_cast<unsigned long>(this) ;

    if (sync) {
        logger.info() << "synchronizing Xlib";
        XSynchronize(m_display, True) ;
    }
    XSetErrorHandler(report_protocol_errors) ;
    XSetIOErrorHandler( report_fatal_errors) ;
}

// Destructor: close connection to X server
display::~display()
{
    if (!m_fatal) {
        logger.info() << "closing connection to X server" ;
        XCloseDisplay(m_display) ;
    }

    logger.debug() << "erasing display object ["
                   << reinterpret_cast<unsigned long>(m_display)
                   << ", "
                   << reinterpret_cast<unsigned long>(this)
                   << "] from internal registry" ;
    m_display_map.erase(m_display) ;
}

//------------------------- ERROR HANDLING -----------------------------

// DEVNOTE: We should not throw a protocol_error exception from this
// callback function. In fact, we should not throw any C++ exceptions
// from this callback because it is called by Xlib, a C library that
// likely cannot and does not play well with exceptions, stack unwinding
// etc. See, for example,
// http://stackoverflow.com/questions/10318363/is-it-safe-for-xs-error-handler-to-throw-exceptions.
//
// In fact, throwing an exception in this callback results in the Minx
// process going into some weird state where it starts consuming 100%
// CPU. So, really, that's a very bad idea...
//
// Since minxlib is meant to be used from Python, what we really want to
// do is inform the Python interpreter of an error condition and have it
// raise an exception. We can still leverage the Python interface
// provided by Boost.Python as long as we don't throw an exception,
// i.e., no calls to boost::python::throw_error_already_set().
//
// This is why minxlib's exception classes hide their constructors and
// require clients (such as the minxlib::display class) call a raise
// method to deliver exceptions to the Python core of Minx. That way,
// each exception class can implement an appropriate way to report
// errors to the Python side of Minx (whether that is using the Python C
// API or actually throwing a C++ exception).
int display::report_protocol_errors(Display*, XErrorEvent* e)
{
    protocol_error::raise(e) ;
    return 0 ;
}

// See comment preceding previous function, viz.,
// display::report_protocol_errors(). The same applies to this one.
int display::report_fatal_errors(Display* d)
{
    m_display_map[d]->m_fatal = true ;
    fatal_error::raise() ;
    return -1 ;
}

//---------------------------- Xlib API --------------------------------

window
display::
create_window(const window& parent, int x, int y, int width, int height)
{
    throw_fatal() ;

    Window w = XCreateSimpleWindow(m_display, parent,
                                   x, y, width, height, 0, 0, 0) ;
    return window(m_display, w) ;
}

std::vector<root_window> display::get_root_windows()
{
    throw_fatal() ;

    std::vector<root_window> root_windows ;

    int n = 0 ;
#ifdef MINXLIB_HAS_XINERAMA
    XineramaScreenInfo* screens = XineramaQueryScreens(m_display, &n) ;
    if (n > 0)
    {
        logger.info() << "Xinerama enabled; " << n << " screens" ;
        root_windows.reserve(n) ;
        for (int i = 0; i < n; ++i)
            root_windows.push_back(root_window(m_display, i, screens[i])) ;
        XFree(screens) ;
    }
    else
#endif
    {
        n = ScreenCount(m_display) ;
        logger.info() << "no Xinerama; " << n << " independent screens" ;
        root_windows.reserve(n) ;
        for (int i = 0; i < n; ++i)
            root_windows.push_back(root_window(m_display, i)) ;
    }
    return root_windows ;
}

std::vector<window> display::get_top_level_windows()
{
    throw_fatal() ;

    std::vector<window> windows ;
    int num_screens = ScreenCount(m_display) ;
    for (int screen = 0; screen < num_screens; ++screen)
    {
        logger.debug() << "getting top-level windows on screen " << screen ;
        Window  root, parent ;
        Window* children = 0 ;
        unsigned int num_children ;
        Status s = XQueryTree(m_display, RootWindow(m_display, screen),
                              &root, &parent, &children, &num_children) ;
        if (!s) {
            logger.warning() << "unable to query screen " << screen ;
            continue ;
        }
        if (children) {
            for (unsigned int i = 0; i < num_children; ++i) {
                logger.debug() << "screen "   << screen
                               << ", window " << i << " = " << children[i] ;
                windows.push_back(window(m_display, children[i])) ;
            }
            XFree(children) ;
        }
    }
    logger.info() << "total number of top-level windows = " << windows.size() ;
    return windows ;
}

window display::get_focused_window()
{
    throw_fatal() ;

    Window w ; int r ;
    XGetInputFocus(m_display, &w, &r) ;
    logger.debug() << "currently focused window = " << w ;
    return  window(m_display, (w == PointerRoot || w == None) ? 0 : w) ;
}

std::vector<std::string> display::get_keyboard_mapping()
{
    throw_fatal() ;

    int min_keycode, max_keycode ;
    XDisplayKeycodes(m_display, &min_keycode, &max_keycode) ;
    logger.debug() << "keycode range = ["
                   << min_keycode << ' ' << max_keycode << ']' ;

    const int keycode_count = max_keycode - min_keycode + 1 ;
    int keysyms_per_keycode ;
    KeySym* keysyms =
       XGetKeyboardMapping(m_display, min_keycode, keycode_count,
                           &keysyms_per_keycode) ;
    logger.debug() << "keysyms per keycode = " << keysyms_per_keycode ;

    std::set<std::string> mapping ;
    if (keysyms) {
        const int n = keycode_count * keysyms_per_keycode ;
        logger.debug() << "converting " << n << " total keysyms to strings" ;
        for (int i = 0; i < n; ++i) {
            char*p = XKeysymToString(keysyms[i]) ;
            if (p != NULL)
                mapping.insert(p) ;
        }
        XFree(keysyms) ;
    }
    else
        logger.warning() << "XGetKeyboardMapping() returned no keysyms" ;
    return std::vector<std::string>(mapping.begin(), mapping.end()) ;
}

boost::shared_ptr<event> display::get_event()
{
    throw_fatal() ;

    XEvent e ;
    XNextEvent(m_display, &e) ;
    return event::create(e, m_display) ;
}

//------------------------ PYTHON INTERFACE ----------------------------

// Export display class to Python
void display::pythonize()
{
    py::class_<display, boost::noncopyable>("display",
        py::init<std::string, bool>((py::arg("name") = std::string(""),
                                     py::arg("sync") = false ))).
        def("create_window",         &display::create_window   ).
        def("get_root_windows",      &display::get_root_windows).
        def("get_top_level_windows", &display::get_top_level_windows).
        def("get_focused_window",    &display::get_focused_window   ).
        def("get_keyboard_mapping",  &display::get_keyboard_mapping ).
        def("get_event",             &display::get_event) ;

    logger = logging::get_logger("display") ;
}

} // namespace minxlib

//----------------------------------------------------------------------

/**********************************************/
/* Editor config:                             */
/**********************************************/
/* Local Variables:                           */
/* indent-tabs-mode: nil                      */
/* c-basic-offset: 4                          */
/* End:                                       */
/**********************************************/
/* vim: set expandtab shiftwidth=4 tabstop=4: */
/**********************************************/

/**
    @file  display.hh
    @brief Encapsulation of connection to X server.

    This file defines a class that takes care of the details of
    connecting to the X server and provides an API for the rest of Minx
    to interface with the relevant aspects of Xlib.

    DEVNOTE: Since Minx is implemented in Python, the minxlib API is
    exported from C++ to Python using Boost.Python. We could have used
    python-xlib instead of writing a custom Xlib wrapper for Minx.
    Unfortunately, python-xlib is not very well documented, which makes
    it difficult to use. Since the C interface to Xlib is reasonably
    well documented, it is much easier to create an appropriate wrapper
    around that.

    Furthermore, a custom wrapper allows us to abstract away the
    interface to the display server, thus, making it easier to port Minx
    to, say, Wayland (if and when that becomes necessary). The Python
    parts of Minx can remain unchanged; all we would have to do is
    implement the appropriate interfaces to the new display server
    protocol in minxlib. At least, that is the hope...

    NOTE: minxlib is not meant to be a generic Xlib wrapper. It is
    designed specifically to be used by Minx. So, only those aspects of
    Xlib that Minx needs are wrapped. Moreover, the wrapping provides
    high-level API's that are only sensible for Minx.
*/

/*
    Copyright (C) 2012 The Minx Project Developers

    See wiki/copyright.wiki for the full list of authors who have
    contributed to this project.
*/

/*
    This file is part of Minx.

    Minx is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Minx is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
    License for more details.

    You should have received a copy of the GNU General Public License
    along with Minx. If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef MINXLIB_DISPLAY_DOT_HH
#define MINXLIB_DISPLAY_DOT_HH

//----------------------------- HEADERS --------------------------------

// minxlib
#include "exception.hh"

// Xlib
#include <X11/Xlib.h>

// Boost
#include <boost/shared_ptr.hpp>
#include <boost/utility.hpp>

// Standard C++
#include <map>
#include <vector>
#include <string>

//------------------------- CLASS DEFINITION ---------------------------

namespace minxlib {

// Forward declarations
class event ;
class window;
class root_window ;

/**
    @brief Encapsulate the details of the connection to the X server.

    This class provides an API for the Python parts of Minx to be able
    to talk to the display server. It wraps around the relevant parts of
    Xlib and exposes its functionality to Python via @boostpylink.

    This class is meant to be used by the @ref minx.core.wm.wm
    "minx.core.wm" Python class. When end-user Minx configs start-up the
    window manager, they will instantiate minx.core.wm, which, in turn,
    will create an instance of minxlib::display to establish the
    connection to the X server.

    @note This class should only be instantiated once and really should
    not be subclassed. However, there is nothing in its implementation
    to prevent you from creating multiple minxlib::display objects or
    from subclassing it.

    @par
    Nonetheless, it is rare to ever want to have more than one instance
    of this class, to subclass it, or to want to access it from multiple
    thread contexts. If you need to do such things, you will have to
    take care of the details of tracking the multiple connections,
    accessing them from different threads, etc.

    @par
    In short, don't do these funky things; minxlib and the minx library
    are not designed for it and you really shouldn't need such
    functionality anyway (multithreaded window manager with multiple
    connections to the X server? really? why? don't you have enough
    problems in your life already?).
*/
class display: boost::noncopyable {
    // A display object's basic purpose is to wrap around the Xlib
    // Display structure.
    Display* m_display ;

    // Keep track of the instances of this class and their corresponding
    // X connections. We need this because the Xlib error handler
    // callbacks don't support passing back any client data. Thus, if we
    // encounter a fatal error, there's no way to have Xlib pass back
    // the display object corresponding to the Display pointer that we
    // can then readily mark as being in an unusable state.
    // Consequently, we have to keep track of this ourselves.
    //
    // DEVNOTE: We're maintaining this map so that in case of fatal X
    // errors, we can set a fatal flag in the display object. Then, if
    // some smartass end-user decides to ignore the fatal error
    // condition and tries to continue using the display object, we can
    // keep throwing fatal_error exceptions to foil this attempt at
    // abuse.
    //
    // DEVNOTE 2: Usually, there will only be one connection to the X
    // server. So, we may be able to get away with a single static
    // Display*. However, we cannot be guaranteed that there will only
    // ever be one instance of this class. Explicitly guaranteeing it
    // ourselves by limiting the number of display objects that can be
    // created will complicate the implementation and, potentially, the
    // interface of this class. Much easier to just use a map and be
    // done with it even though the map will pretty much always contain
    // just a single element.
    static std::map<Display*, display*> m_display_map ;

    // Flag to indicate whether or not a fatal error has occurred on
    // this connection to the X server.
    bool m_fatal ;

    // Helper function to check fatal flag and throw a fatal_error in
    // case it is set. This function should be called at the beginning
    // of each public API.
    void throw_fatal() {if (m_fatal) fatal_error::throw_it() ;}

public:
    /**
        @brief  Open a connection to the X server.
        @param  name Name of the X server.
        @param  sync Flag for synchronizing Xlib requests.
        @return A valid connection to the display server.

        Instantiating a minxlib::display object automatically sets up a
        connection to the X server. If the connection fails, a
        connection_error will be thrown.

        The name parameter will usually be an empty string, in which
        case, the contructor will connect to the X server specified by
        the DISPLAY environment variable. If specified, it should be
        something like "host:0.0". Look up X server and Xlib
        documentation to get the low-down on this.

        The sync flag indicates whether we want Xlib requests to be
        synchronous or not. By default, it is false, i.e., Xlib requests
        are buffered. Turning synchronization on is useful for
        debugging. Note that the choice between synchronous and buffered
        mode of operation is decided at creation time. That is, it
        cannot be toggled after a display object has been instantiated.

        In addition to establishing the connection to the display
        server, this constructor will also setup Xlib error handlers.
        When the X server flags errors by invoking the handlers, they
        will be reported to Python clients via appropriate
        @ref grp_minxlib_exceptions "Python exceptions".

        In case a fatal error is reported, clients are expected to
        clean-up and then terminate the process. The display object will
        become unusable after a fatal_error exception is thrown. Any
        attempt to use it after a fatal error will result in continued
        fatal_error exceptions.
    */
    display(const std::string& name = std::string(), bool sync = false) ;

    /**
        @brief  Close the connection to the X server.
        @return Nothing.

        When a display object is destroyed, it will automatically sever
        its connection to the display server.
    */
    ~display() ;

    /**
        @brief  Export the display class to minxlib Python module.
        @return Nothing.

        This function exposes the display class's interface so that it
        can be used by the Python parts of Minx. It is meant to be
        called by the Boost.Python initialization code in python.cc.
    */
    static void pythonize() ;

    /**
        @brief  Create a window.
        @param  p The new window's parent window.
        @param  x The x-coordinate of the new window's origin.
        @param  y The y-coordinate of the new window's origin.
        @param  w The new window's width.
        @param  h The new window's height.
        @return The newly created window.

        This function creates a new window by calling
        XCreateSimpleWindow(), wraps the result in a minxlib::window
        object and returns that.

        The parameter p <b>must</b> be an existing window; x and y are
        relative to the parent's origin.

        @note Although this function can churn out arbitrary windows
        parented by arbitrary other windows, end-user code should most
        definitely not abuse it in that manner. It is meant to be used
        only to create layouts.
    */
    window create_window(const window& p, int x, int y, int w, int h) ;

    /**
        @brief  Retrieve the list of root windows.
        @return List of root windows.

        This function queries the X server for all its screens and their
        corresponding root windows. The returned list holds the root
        windows in the screen order, i.e., the first element of the list
        is the root window for the first screen, the second is the root
        window for the second screen, so on and so forth.

        @note On multi-head setups with Xinerama, there is only one
        screen, and, thus, only one root window as far as the X server is
        concerned. Nonetheless, this function will still return as many
        root windows as there are physical monitors; each of these root
        windows will have the same window ID, but their geometries will
        be different.
    */
    std::vector<root_window> get_root_windows() ;

    /**
        @brief  Retrieve top-level windows across all screens.
        @return List of top-level windows.

        This function queries the X server for all the top-level windows
        on all screens. Do not rely on the returned list being in any
        particular order.

        This function is meant to be used by
        @ref minx.core.wm.wm "minx.core.wm" just before it enters its
        event loop so that Minx can manage any extant top-level windows
        that were created before Minx was started.
    */
    std::vector<window> get_top_level_windows() ;

    /**
        @brief  Get the window with the input focus.
        @return Currently focused window.

        This function uses XGetInputFocus() to determine which X window
        currently has the input focus and returns that wrapped in a
        @ref minxlib::window "minxlib::window" object.

        If no window has the input focus, this function will return a
        window with the ID zero.
    */
    window get_focused_window() ;

    /**
        @brief  Retrieve currently supported keysyms in string form.
        @return List of strings containing current keysyms.

        The X server assigns unique integer codes to each physical key
        on the keyboard. However, since different keyboard models and
        brands can have different keycodes, applications usually deal
        with keysyms, which are the symbols on the key caps (this is an
        oversimplification, but good enough for explanatory purposes).

        This function queries the X server for its mapping between
        keycodes and keysyms, converts the keysyms to strings, and
        returns the resulting list.
    */
    std::vector<std::string> get_keyboard_mapping() ;

    /**
        @brief  Retrieve the next event from the X server.
        @return A minxlib::event object describing the X event.

        This function removes the next event from the X event queue and
        returns it to its caller via an instance of a subclass of
        minxlib::event. This function is meant to be used by
        @ref minx.core.wm.wm "minx.core.wm" in its event loop.
    */
    boost::shared_ptr<event> get_event() ;

private:
    /**
        @brief  Report protocol errors via an exception.
        @param  d The connection to the X server.
        @param  e The Xlib error structure.
        @return Nothing.

        This function serves as the callback for the Xlib error handler.
        It simply raises an exception so that Python clients are
        informed of X protocol errors.

        In some cases, it may be possible to recover from protocol
        errors. In others, you may have little choice but to clean-up
        and quit.
    */
    static int report_protocol_errors(Display* d, XErrorEvent* e) ;

    /**
        @brief  Report fatal X errors via an exception.
        @param  d The connection to the X server.
        @return Nothing.

        This function serves as the callback for the Xlib I/O error
        handler. It simply raises an exception so that Python clients
        are informed of fatal X errors. When a client receives a
        fatal_error exception, it is expected to clean-up and terminate
        its process. Making further Xlib calls via minxlib will result
        in continued fatal_error exceptions.

        DEVNOTE: Since this Xlib callback does not support passing back
        arbitrary client data, we have to resort to using the
        m_display_map defined above to be able to keep throwing
        fatal_error exceptions after an X fatal error.
    */
    static int report_fatal_errors(Display* d) ;
} ; // class display

} // namespace minxlib

//----------------------------------------------------------------------

#endif // #ifndef MINXLIB_DISPLAY_DOT_HH

/**********************************************/
/* Editor config:                             */
/**********************************************/
/* Local Variables:                           */
/* indent-tabs-mode: nil                      */
/* c-basic-offset: 4                          */
/* End:                                       */
/**********************************************/
/* vim: set expandtab shiftwidth=4 tabstop=4: */
/**********************************************/