Gravitating vortices, cosmic strings, and the Kähler--Yang--Mills equations