.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. currentmodule:: wx.lib.pubsub.core.topicmgr

.. highlight:: python



.. _wx.lib.pubsub.core.topicmgr.TopicManager:

==========================================================================================================================================
|phoenix_title|  **wx.lib.pubsub.core.topicmgr.TopicManager**
==========================================================================================================================================

Manages the registry of all topics and creation/deletion
of topics. 

Note that any method that accepts a topic name can accept it in the 
'dotted' format such as ``'a.b.c.'`` or in tuple format such as 
``('a', 'b', 'c')``. Any such method will raise a ValueError
if name not valid (empty, invalid characters, etc). 



|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>TopicManager</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.lib.pubsub.core.topicmgr.TopicManager_inheritance.png" alt="Inheritance diagram of TopicManager" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.pubsub.core.topicmgr.TopicManager.html" title="wx.lib.pubsub.core.topicmgr.TopicManager" alt="" coords="5,5,304,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.__init__`                       The optional treeConfig is an instance of TreeConfig, used to
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.addDefnProvider`                Register a topic definition provider. After this method is called, whenever a topic must be created,
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.checkAllTopicsHaveMDS`          Check that all topics that have been created for their MDS.
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.clearDefnProviders`             Remove all registered topic definition providers
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.delTopic`                       Delete the named topic, including all sub-topics. Returns ``False`` if topic does not exist; ``True`` otherwise. Also unsubscribe any listeners
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getNumDefnProviders`            Get how many topic definitions providers are registered.
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getOrCreateTopic`               Get the Topic instance for topic of given name, creating it
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getRootAllTopics`               Get the topic that is parent of all root (ie top-level) topics,
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getTopic`                       Get the Topic instance for the given topic name. By default, raises
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getTopicsSubscribed`            Get the list of Topic objects that have given listener
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.hasTopicDefinition`             Determine if there is a definition avaiable for topic 'name'. Return
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.isTopicInUse`                   Determine if topic 'name' is in use. ``True`` if a Topic object exists
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.newTopic`                       Deprecated legacy method.
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: TopicManager

   Manages the registry of all topics and creation/deletion
   of topics. 
   
   Note that any method that accepts a topic name can accept it in the 
   'dotted' format such as ``'a.b.c.'`` or in tuple format such as 
   ``('a', 'b', 'c')``. Any such method will raise a ValueError
   if name not valid (empty, invalid characters, etc). 

   .. method:: __init__(self, treeConfig=None)

      The optional treeConfig is an instance of TreeConfig, used to
      configure the topic tree such as notification settings, etc. A
      default config is created if not given. This method should only be 
      called by an instance of Publisher (see Publisher.getTopicManager()).


   .. method:: addDefnProvider(self, providerOrSource, format=None)

      Register a topic definition provider. After this method is called, whenever a topic must be created,
      the first definition provider that has a definition
      for the required topic is used to instantiate the topic. 
      
      If providerOrSource is an instance of ITopicDefnProvider, register 
      it as a provider of topic definitions. Otherwise, register a new 
      instance of TopicDefnProvider(providerOrSource, format). In that case, 
      if format is not given, it defaults to TOPIC_TREE_FROM_MODULE. Either
      way, returns the instance of ITopicDefnProvider registered.


   .. method:: checkAllTopicsHaveMDS(self)

      Check that all topics that have been created for their MDS.
      Raise a TopicDefnError if one is found that does not have one.


   .. method:: clearDefnProviders(self)

      Remove all registered topic definition providers


   .. method:: delTopic(self, name)

      Delete the named topic, including all sub-topics. Returns ``False`` if topic does not exist; ``True`` otherwise. Also unsubscribe any listeners 
      of topic and all subtopics. 


   .. method:: getNumDefnProviders(self)

      Get how many topic definitions providers are registered.


   .. method:: getOrCreateTopic(self, name, protoListener=None)

      Get the Topic instance for topic of given name, creating it
      (and any of its missing parent topics) as necessary. Pubsub 
      functions such as subscribe() use this to obtain the Topic object
      corresponding to a topic name. 
      
      The name can be in dotted or string format (``'a.b.'`` or ``('a','b')``). 
      
      This method always attempts to return a "complete" topic, i.e. one 
      with a Message Data Specification (MDS). So if the topic does not have 
      an MDS, it attempts to add it. It first tries to find an MDS 
      from a TopicDefnProvider (see addDefnProvider()). If none is available, 
      it attempts to set it from protoListener, if it has been given. If not, 
      the topic has no MDS. 
      
      Once a topic's MDS has been set, it is never again changed or accessed
      by this method. 
              
      Examples::
          
          # assume no topics exist
          # but a topic definition provider has been added via 
          # pub.addTopicDefnProvider() and has definition for topics 'a' and 'a.b'
          
          # creates topic a and a.b; both will have MDS from the defn provider:
          t1 = topicMgr.getOrCreateTopic('a.b')
          t2 = topicMgr.getOrCreateTopic('a.b')
          assert(t1 is t2)
          assert(t1.getParent().getName() == 'a')
          
          def proto(req1, optarg1=None): pass
          # creates topic c.d with MDS based on proto; creates c without an MDS
          # since no proto for it, nor defn provider:
          t1 = topicMgr.getOrCreateTopic('c.d', proto)
          
      The MDS can also be defined via a call to subscribe(listener, topicName), 
      which indirectly calls getOrCreateTopic(topicName, listener).


   .. method:: getRootAllTopics(self)

      Get the topic that is parent of all root (ie top-level) topics,
      for default TopicManager instance created when this module is imported. 
      Some notes:
      
      - "root of all topics" topic satisfies isAll()==True, isRoot()==False,
        getParent() is None;
      - all root-level topics satisfy isAll()==False, isRoot()==True, and
        getParent() is getDefaultTopicTreeRoot();
      - all other topics satisfy neither. 


   .. method:: getTopic(self, name, okIfNone=False)

      Get the Topic instance for the given topic name. By default, raises
      an TopicNameError exception if a topic with given name doesn't exist. If
      okIfNone=True, returns None instead of raising an exception.


   .. method:: getTopicsSubscribed(self, listener)

      Get the list of Topic objects that have given listener
      subscribed. Note: the listener can also get messages from any 
      sub-topic of returned list.


   .. method:: hasTopicDefinition(self, name)

      Determine if there is a definition avaiable for topic 'name'. Return
      true if there is, false otherwise. Note: a topic may have a
      definition without being in use, and vice versa.


   .. method:: isTopicInUse(self, name)

      Determine if topic 'name' is in use. ``True`` if a Topic object exists
      for topic name (i.e. message has already been sent for that topic, or a 
      least one listener subscribed), false otherwise. Note: a topic may be in use 
      but not have a definition (MDS and docstring); or a topic may have a
      definition, but not be in use.


   .. method:: newTopic(self, _name, _desc, _required=(), \*\*_argDocs)

      Deprecated legacy method.
      If topic _name already exists, just returns it and does nothing else.
      Otherwise, uses getOrCreateTopic() to create it, then sets its
      description (_desc) and its message data specification (_argDocs
      and _required). Replaced by getOrCreateTopic().


