draw_handler_add() and draw_handler_remove()

Question

The bpy.types.Space class has two methods draw_handler_add() and draw_handler_remove(). However, the documentation for those methods only says, "Undocumented." Thus, what are those methods for?

Answer 1

Assign a draw callback on a space.

It is used to assign a draw callback to a space. Basically every time the space is redrawn it calls the assigned method. Most often used in conjunction with bgl and blf to draw overlay on the screen.

See the modal draw template 'Text Editor > Templates > Python > Operator Modal Draw'.

In which the draw call back method is

def draw_callback_px(self, context):
    ...

The modal timer operator when run adds a draw call back, aptly named draw_callback, to the 3D View space bpy.types.SpaceView3D and stores the (handler's) handle to self._handle (the handlers are internally assigned to a list on the space class. (Very similarly to application handlers)

        self._handle = bpy.types.SpaceView3D.draw_handler_add(draw_callback_px, args, 'WINDOW', 'POST_PIXEL')

The arguments, are passed using a list of args args = (self, context)

While the operator is running it draws on the screen everytime the window 'WINDOW' draws a ''POST_PIXEL'' event.

When the operator finishes the handler, with handle self._handle is removed..

See examples:

How to draw geometry in 3d View window with bgl

How can i add a text help window and a help button into the 3D View?

https://blender.stackexchange.com/a/113937/15543

In the last link, the draw callback is being used to listen for changes to text files. Not sure it is good practice to do such as it seems to break the no changes in draw methods paradigm: ,in experimenting I added a rotation increment to context.object .. which while text space draw handler is active makes the object rotate in conjunction with scrolling, typing