Please add possible events to scan for to documentation

[RomanSC]

Documentation here gives one example which works perfectly, however...
https://i3ipc-python.readthedocs.io/en/latest/#listening-to-events

There's no actual list that I've been able to find telling me what events I can listen for. I'm refering to the first argument in i3ipc.on('workspace::focus', on_workspace_focus)

i3.on('workspace::focus', on_workspace_focus) # when current workspace changes

With my code below all three of the following don't appear to do anything but they exist (really they certainly do 'something' I just haven't figured it out yet):

i3.on("mode::change", on_mode_changed) # ???
i3.on("binding::mode", on_mode_changed) # ???
i3.on("mode::binding", on_mode_changed) # ???

import i3ipc

i3 = i3ipc.Connection()

# # Define a callback to be called when you switch workspaces.
# def on_workspace_focus(self, e):
#     # The first parameter is the connection to the ipc and the second is an object
#     # with the data of the event sent from i3.
#     if e.current:
#         print('Windows on this workspace:')
#         for w in e.current.leaves():
#             print(w.name)

# # Dynamically name your workspaces after the current window class
# def on_window_focus(i3, e):
#     focused = i3.get_tree().find_focused()
#     ws_name = "%s:%s" % (focused.workspace().num, focused.window_class)
#     i3.command('rename workspace to "%s"' % ws_name)

# Subscribe to events
# i3.on('workspace::focus', on_workspace_focus)
# i3.on("window::focus", on_window_focus)

# Start the main loop and wait for events to come in.
# i3.main()

def on_mode_changed(self, obj):
    if obj.current:
        print(obj.data)
        print(obj.data.name)
        print(dir(obj))

def on_workspace_changed(self, obj):
    if obj.current:
        print(obj.current.name)
        # for x in obj.current:
        #     print(x)

i3.on("mode::change", on_mode_changed)
i3.on("binding::mode", on_mode_changed)
i3.on("mode::binding", on_mode_changed)

i3.on("workspace::focus", on_workspace_changed)

i3.main()

If the documentation simply listed all possible events I could just test and find out myself, what they do:

import i3ipc

i3 = i3ipc.Connection()

def test_event(self, obj):
    # self contains everything in the global
    # scope including i3
    print(dir(obj))

i3.on("workspace::focus", test_event) # returns an object

i3.main()

If I can get a list I would like to help improve documentation if possible.

Thanks

[acrisci]

Hi,

Thanks for your interest in the project. Any improvement to the documentation would be very much appreciated.

The first argument to Connection::on() is a string of the form "<event>::<change_filter>".

The ::<change_filter> part is optional. It is a convenience that I put in the library because most of the time I only care about one change type. Only the name of the event is required. When no change filter is present, you get all the events for the one you specify.

Look at the i3 documentation for events for a list of events.

Each event has a "change" field in the json that is returned. This is what is being filtered by the change filter. Only when the "change" field matches what you give after the :: part will you get the event you want.

I don't think there is a complete list of the possible values for change available outside of the source. You'll need to look at the source in i3 to come up with this list.

If you document all these and put it in the docs folder, that would be a good contribution to the project.

Also feel free to improve these docs from the perspective of a new user.

Another great way to improve the project is by writing tests.