Window naming conventions
KVIrc window structure and the window naming conventions
Introduction
Starting from the release 3.0.0, KVIrc window structure has grown in complexity. Older releases allowed one connection per frame window and thus had a dedicated command parser for each connection. Finding a window in that scenario was quite easy: it was enough to designate it by name (that was exactly the text displayed in the window caption). It was sufficient to have an unique name for ever window; condition that was granted by the underlying IRC protocol and by the KVIrc core design.
In this version, the unique window names are impossible to be granted.
Scenario
The command parser is now global to the application. There can be two or more consoles in each frame and the user is able to join the same channel with two different nicknames using two separate connections.
  • Application (Unique command parser)     
          
    •     Frame X         
                
      •         Console M (IRC context)             
                      
        • Channel windows
          •             
        • Query windows
          •             
        • Other connection related windows
          •             
                
        •         
      •         Console N (IRC context)             
                      
        • Channel windows
          •             
        • Query windows
          •             
        • Other connection related windows
          •             
                
        •         
      •         Other windows         
        •         
      •         ...         
        •         
          
      •     
    •     Frame Y         
                
      •         Console O (IRC context)             
                      
        • Channel windows
          •             
        • Query windows
          •             
        • Other connection related windows
          •             
                
        •         
      •         Console P (IRC context)             
                      
        • Channel windows
          •             
        • Query windows
          •             
        • Other connection related windows
          •             
                
        •         
      •         Other windows         
        •         
      •         ...         
        •         
          
      •     
    •     ...     
      •     

A naming convention has become necessary to resolve ambiguities.
Basic assumptions
Every KVIrc window has four main properties:
-an unique numeric identifier
-the logical name
-the type identifier
-the caption text
The numeric identifier is unique to the whole application, and is the one returned by the $window function.
The identifier is assigned by KVIrc when the window is created and is not changed until the window is destroyed. This identifier will be referred as window ID.
The logical name is a property of some kind of windows. It usually corresponds to the first part of the window caption. For example, for channel windows it is the channel name, for queries it is the list of the targets. For some other windows the logical name corresponds to the caption text. This will be discussed later.
The type identifier describes the properties of a certain window. For channel windows the type identifier is channel, for query windows is query, for console windows it is console, etc.
IRC Contexts
The KVIrc frame windows are numbered starting from 0 and named frame_<number>. Each frame can contain an unlimited number of consoles.
Each console is bound to an IRC context. (The part is bound to could be substituted by defines or is contained in).
An IRC context is a set of resources that can deal with a single IRC connection.
The association between an IRC context and a console is bijective: each IRC context is associated to a single console window.
An IRC context can be in connected or not-connected state. When in connected state, it contains a set of windows beside the console: mainly channels and query windows. The channels and query windows can exist only if the associated IRC context exists.
Channels and queries have unique names inside a connection so there is no way to confuse it. (Theoretically there can be more than one query window with the same name, but in fact all the windows refer to the same target so they are instances of the same resource). All this creates a sort of namespace: the channels and queries can be identified as bound to a specific IRC context.
An IRC context can contain other windows, such as the sockets window or the list window. KVIrc takes care of making them unique inside the IRC context namespace.
Each IRC context has its own unique IRC context ID (see $context).
Since to a single IRC context may correspond only a single IRC connection, when in connected state, the IRC context may be referred also as connection or connection context, and the associated IRC context Id can be referred as connection ID or connection context ID.
There are classes of windows that are not bound to any IRC context: this includes user created windows, DCC windows, browsers etc.
KVIrc will try to keep that windows with unique logical names.
How to identify a window
So what we have until now is:
  • Each window has its own unique window ID: we will refer windows always using this identifier.
  • Each window has a set of properties including: window type, logical name.
  • Subsets of windows are bound to a single IRC context
The simplest (but also the less significant) method of looking for a window is to finding it by caption.
The $window function finds the first KVIrc window matching the caption text and returns its window ID.
This method will likely fail when there are more windows with the same caption text; for this reason several specific functions have been added to allow finding the correct window.
The $console finds a console window bound to a specified IRC context.
The $channel finds a channel window matching the specified name and bound to a specified IRC context.
The $query finds a query window that has a specified target and is bound to a specified IRC context.
Index, Language Overview
KVIrc 5.2.0.5.2.0 Documentation - generated by pragma on Sun Jan 14 18:20:53 2024